@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Tour/Tour.tsx

@@ -0,0 +1,617 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import {
+  arrow,
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useFloating,
+  type Placement,
+} from '@floating-ui/react-dom';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import { Cluster } from '../Cluster';
+import { CircularProgress } from '../CircularProgress';
+import { Stack } from '../Stack';
+import { useTranslation } from '../../i18n/useTranslation';
+import {
+  TOUR_CURRENT_TARGET,
+  overlayStack,
+  useFloatingSurface,
+  useFocusTrap,
+} from '../_internal/overlay';
+import { mergeRefs, sanitizeId } from '../_internal/refs';
+import { useControllableState } from '../_internal/useControllableState';
+import { Spotlight } from './Spotlight';
+import { useTourTarget } from './useTourTarget';
+import styles from './Tour.module.scss';
+
+/** Preferred side of the target for the card. Auto-flips on collision. */
+export type TourSide = 'top' | 'right' | 'bottom' | 'left';
+/** Which card edge aligns with the matching target edge. */
+export type TourAlign = 'start' | 'center' | 'end';
+/** Why a tour ended: `'completed'` = Done on the last step; `'skipped'` = Skip or Escape. */
+export type TourFinishReason = 'completed' | 'skipped';
+
+/** One step of a `<Tour>`. Plain data — keep tours in a config module. */
+export interface TourStep {
+  /**
+   * `data-tour` value of the element to spotlight (`<Button data-tour="bulk-edit">`
+   * ↔ `target: 'bulk-edit'`). Omit for a centered step with no spotlight
+   * (welcome / finish). If the target isn't mounted yet the Tour waits for it
+   * — see `targetTimeout`.
+   */
+  target?: string;
+  /** Card heading; also the dialog's accessible name. */
+  title: ReactNode;
+  /** Card text; also the dialog's accessible description. Links, `Kbd`, etc. are fine. */
+  body?: ReactNode;
+  /** Preferred side of the target. Default `'bottom'`. Auto-flips if it doesn't fit. */
+  side?: TourSide;
+  /** Edge alignment against the target. Default `'center'`. */
+  align?: TourAlign;
+  /** Px of spotlight around the target. Default `8`. */
+  spotlightPadding?: number;
+  /**
+   * Modal mode only. The target stays clickable through the spotlight and joins
+   * the focus trap — for "click X to continue" steps. Default `false`
+   * (look-only: the target is blocked like the rest of the page).
+   */
+  interactive?: boolean;
+  /**
+   * `'click'` advances to the next step after the target's own click handler
+   * runs. Needs a clickable target: `interactive: true` in modal mode, or any
+   * step with `modal={false}`. Ignored (dev warning) otherwise.
+   */
+  advanceOn?: 'click';
+  /**
+   * What the card's Next / Done / ArrowRight does on a click-to-continue step
+   * (`advanceOn: 'click'`). Ignored on any other step.
+   * - `'click'` (default) — activates the target (a full pointer sequence), so
+   *   the step's own action runs, then the tour advances.
+   * - `'skip'` — advances without touching the target. Choose it when the
+   *   target's action has side effects Next shouldn't trigger (a delete, a
+   *   save, a navigation). The hint, the secondary Next and the waves stay;
+   *   a real click on the target still advances.
+   */
+  next?: 'click' | 'skip';
+}
+
+export interface TourProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> {
+  /** The steps, in order. Must be non-empty. */
+  steps: TourStep[];
+  /**
+   * Controlled open state (required — like `Modal`, there is no uncontrolled
+   * mode: an uncontrolled tour could not be started or replayed).
+   */
+  open: boolean;
+  /** Called with `false` on Skip, Escape and Done. */
+  onOpenChange: (open: boolean) => void;
+  /**
+   * Fires once per Skip / Escape / Done. NOT called when the consumer closes
+   * the tour itself by setting `open={false}` — only the tour's own end
+   * gestures fire it. Use it to persist "seen" state.
+   */
+  onFinish?: (reason: TourFinishReason) => void;
+  /**
+   * Controlled step index. Control it when a step change must do something
+   * first — navigate to another page, open an accordion, switch a tab — then
+   * the Tour waits for the next target to mount.
+   */
+  step?: number;
+  /** Fires on every step change (Next, Back, arrow keys, `advanceOn`), controlled or not. */
+  onStepChange?: (index: number) => void;
+  /** Uncontrolled starting step. Default `0`. Every re-open starts here again. */
+  defaultStep?: number;
+  /**
+   * `true` (default): dims the page with a spotlight cutout, blocks clicks
+   * outside it and traps focus — onboarding. `false`: card only, page stays
+   * usable — feature announcements.
+   */
+  modal?: boolean;
+  /**
+   * Ms to wait for a step's target before falling back to a centered card.
+   * Default `5000` (room for a route change + data fetch). `Infinity` waits forever.
+   */
+  targetTimeout?: number;
+  /** Called when a step's target didn't appear within `targetTimeout`. Log it. */
+  onTargetMissing?: (step: TourStep, index: number) => void;
+  /**
+   * Contextual label for the last step's button, e.g. `'Got it'` for a
+   * one-step announcement. Defaults to the i18n `tour.done` (`'Done'`). An
+   * empty string counts as unset.
+   */
+  doneLabel?: string;
+}
+
+/**
+ * Activates a click-to-continue target. DropdownMenu's trigger toggles on
+ * pointerdown, so a bare click() wouldn't activate it; replay the full
+ * primary-pointer sequence a real click produces.
+ */
+function activate(el: HTMLElement) {
+  const init = { bubbles: true, cancelable: true, button: 0 };
+  const Ptr = typeof window.PointerEvent === 'function' ? window.PointerEvent : MouseEvent;
+  const ptr = { ...init, isPrimary: true, pointerType: 'mouse' };
+  el.dispatchEvent(new Ptr('pointerdown', ptr));
+  el.dispatchEvent(new MouseEvent('mousedown', init));
+  el.dispatchEvent(new Ptr('pointerup', ptr));
+  el.dispatchEvent(new MouseEvent('mouseup', init));
+  el.dispatchEvent(new MouseEvent('click', init));
+}
+
+/** Unmount fallback when `transitionend` never fires (reduced motion, jsdom). */
+export const EXIT_FALLBACK_MS = 300;
+/** Gap in px between target and card (room for the arrow). */
+const CARD_OFFSET = 12;
+/** Viewport edge padding for shift(); mirrored by `--tour-card-viewport-gap` in Tour.tokens.scss. */
+const CARD_VIEWPORT_PADDING = 8;
+/** Arrow keys inside these keep their native meaning (caret, option list). */
+const EDITABLE = 'input, textarea, select, [contenteditable]:not([contenteditable="false"])';
+
+/**
+ * Guided tour that spotlights each step's `data-tour` target and anchors a card with Skip / Back / Next to it.
+ * @see docs/components/Tour.md
+ */
+export const Tour = forwardRef<HTMLDivElement, TourProps>(function Tour(props, ref) {
+  const { open } = props;
+  const [present, setPresent] = useState(open);
+  const [session, setSession] = useState(0);
+  const [prevOpen, setPrevOpen] = useState(open);
+  if (open !== prevOpen) {
+    setPrevOpen(open);
+    if (open) {
+      setPresent(true);
+      setSession((s) => s + 1);
+    }
+  }
+  const onExited = useCallback(() => setPresent(false), []);
+  if (!present) return null;
+  // A fresh session per open resets uncontrolled step state to defaultStep.
+  return <TourSession key={session} {...props} ref={ref} closing={!open} onExited={onExited} />;
+});
+
+interface TourSessionProps extends TourProps {
+  closing: boolean;
+  onExited: () => void;
+}
+
+const TourSession = forwardRef<HTMLDivElement, TourSessionProps>(function TourSession(
+  {
+    steps,
+    open: _open,
+    onOpenChange,
+    onFinish,
+    step: stepProp,
+    onStepChange,
+    defaultStep = 0,
+    modal = true,
+    targetTimeout = 5000,
+    onTargetMissing,
+    doneLabel,
+    closing,
+    onExited,
+    onKeyDown,
+    className,
+    style,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const t = useTranslation();
+  const [index, setIndex] = useControllableState<number>({
+    value: stepProp,
+    defaultValue: defaultStep,
+    onChange: onStepChange,
+  });
+  const current = steps[index];
+  const total = steps.length;
+  const isLast = index === total - 1;
+
+  const uid = sanitizeId(useId());
+  const titleId = `tour-title-${uid}`;
+  const bodyId = `tour-body-${uid}`;
+  const hintId = `tour-hint-${uid}`;
+  const cardRef = useRef<HTMLDivElement | null>(null);
+  const arrowRef = useRef<HTMLSpanElement | null>(null);
+
+  const { element, status } = useTourTarget(current?.target, targetTimeout, () => {
+    if (!current) return;
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[Tour] target "${current.target}" not found after ${targetTimeout}ms; showing step ${index + 1} centered.`,
+      );
+    }
+    onTargetMissing?.(current, index);
+  });
+  const found = status === 'found' ? element : null;
+  const waiting = status === 'waiting';
+  const centered = !found;
+
+  // One tick behind on purpose — see Switch's busyText for why. Mounting the
+  // region and its text together on the first `waiting` render would be
+  // silent for most screen readers; deferring to an effect makes the word
+  // always arrive as a change (Hard rule 10).
+  const [waitingText, setWaitingText] = useState('');
+  useEffect(() => {
+    setWaitingText(waiting && !closing ? t('tour.waiting') : '');
+  }, [waiting, closing, t]);
+
+  // Guards against a consumer whose onOpenChange ignores `false` (so `closing`
+  // never flips true) — Skip then Escape must still fire onFinish only once.
+  // Reset per session: finishedRef is fresh on every TourSession mount
+  // (key={session} in Tour).
+  const finishedRef = useRef(false);
+  const finish = (reason: TourFinishReason) => {
+    if (closing || finishedRef.current) return;
+    finishedRef.current = true;
+    onOpenChange(false);
+    onFinish?.(reason);
+  };
+  const goNext = () => (isLast ? finish('completed') : setIndex(index + 1));
+  const goBack = () => {
+    if (index > 0) setIndex(index - 1);
+  };
+  // Latest-callback ref for listeners registered in effects (advanceOn, keys).
+  const goNextRef = useRef(goNext);
+  goNextRef.current = goNext;
+
+  const finishRef = useRef(finish);
+  finishRef.current = finish;
+
+  // ---- Focus ----
+  // Captured before the card takes focus (effects run in declaration order).
+  const restoreRef = useRef<HTMLElement | null>(null);
+  useLayoutEffect(() => {
+    restoreRef.current = document.activeElement as HTMLElement | null;
+  }, []);
+
+  // Focus the card on open and on every step change so the new title is
+  // announced. preventScroll: the target scroll is ours to control.
+  useLayoutEffect(() => {
+    if (closing) return;
+    queueMicrotask(() => cardRef.current?.focus({ preventScroll: true }));
+  }, [index, closing]);
+
+  // Return focus on close — unless the user has already moved it elsewhere.
+  useEffect(() => {
+    if (!closing) return;
+    const active = document.activeElement;
+    if (active && active !== document.body && !cardRef.current?.contains(active)) return;
+    const el = restoreRef.current;
+    if (el?.isConnected) el.focus({ preventScroll: true });
+  }, [closing]);
+
+  useFocusTrap(cardRef, modal && !closing, modal && current?.interactive ? found : null);
+
+  // ---- Escape = skip ----
+  // Registered as a floating surface so a host Modal yields (#274), and gated
+  // on isTopFloating so a Select/Popover opened in the card closes first (#280).
+  // Gated on `current` too: an empty/out-of-range step renders nothing (see
+  // the early return below), so it must not register as a floating surface
+  // or handle Escape.
+  const floatingId = useFloatingSurface(!closing && !!current);
+  const hasCurrent = !!current;
+  useEffect(() => {
+    if (closing || !hasCurrent) return;
+    const onDocKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape' || !overlayStack.isTopFloating(floatingId)) return;
+      // modal={false} leaves the rest of the page usable, so Escape typed
+      // into an unrelated page control (a filter input, a form field) must
+      // not skip the tour out from under the user — only Escape while focus
+      // is actually in the card counts. Modal mode is unaffected: the page
+      // is blocked behind the scrim, so Escape always means "skip".
+      if (!modal && !cardRef.current?.contains(document.activeElement)) return;
+      e.preventDefault();
+      overlayStack.consumeEscape(e);
+      finishRef.current('skipped');
+    };
+    document.addEventListener('keydown', onDocKeyDown, true);
+    return () => document.removeEventListener('keydown', onDocKeyDown, true);
+  }, [closing, floatingId, hasCurrent, modal]);
+
+  // ---- Positioning ----
+  const side = current?.side ?? 'bottom';
+  const align = current?.align ?? 'center';
+  const placement = (align === 'center' ? side : `${side}-${align}`) as Placement;
+  const {
+    refs,
+    floatingStyles,
+    placement: resolvedPlacement,
+    middlewareData,
+    isPositioned,
+  } = useFloating({
+    open: !!found,
+    placement,
+    strategy: 'fixed',
+    // CSS `transform` stays free for the entrance scale (as in Popover).
+    transform: false,
+    middleware: [
+      offset(CARD_OFFSET),
+      flip(),
+      shift({ padding: CARD_VIEWPORT_PADDING }),
+      arrow({ element: arrowRef }),
+    ],
+    whileElementsMounted: autoUpdate,
+    elements: { reference: found },
+  });
+  const resolvedSide = resolvedPlacement.split('-')[0] as TourSide;
+  const staticSide = ({ top: 'bottom', bottom: 'top', left: 'right', right: 'left' } as const)[
+    resolvedSide
+  ];
+
+  // Glide (top/left/translate + spotlight geometry) only after the first
+  // placement, so nothing sweeps in from the viewport origin on open.
+  const [glide, setGlide] = useState(false);
+  useEffect(() => {
+    if (glide || !(centered || isPositioned)) return;
+    const id = requestAnimationFrame(() => setGlide(true));
+    return () => cancelAnimationFrame(id);
+  }, [glide, centered, isPositioned]);
+
+  // ---- Scroll the target into view ----
+  useEffect(() => {
+    if (!found) return;
+    const r = found.getBoundingClientRect();
+    const inView =
+      r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
+    if (inView) return;
+    const reduce = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches;
+    found.scrollIntoView?.({
+      block: 'center',
+      inline: 'nearest',
+      behavior: reduce ? 'auto' : 'smooth',
+    });
+  }, [found]);
+
+  // ---- advanceOn: 'click' ----
+  // Deps are the two primitives this effect actually reads, not the whole
+  // `current` object — a consumer passing `steps` as an inline array literal
+  // gives `current` a new identity every render even when its content is
+  // unchanged, which would re-attach the click listener on every unrelated
+  // re-render.
+  const advanceOn = current?.advanceOn;
+  const interactive = current?.interactive;
+  // Same condition the effect below uses to actually listen for the click —
+  // including `found`: no target (waiting / centered fallback), no listener.
+  const clickToContinue = advanceOn === 'click' && (!modal || !!interactive) && !!found;
+  // A synthetic click on a disabled control never fires, so skip activating it.
+  const advance = () =>
+    clickToContinue && current?.next !== 'skip' && found && !found.matches(':disabled')
+      ? activate(found)
+      : goNext();
+  useEffect(() => {
+    if (advanceOn !== 'click') return;
+    if (modal && !interactive) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn('[Tour] advanceOn="click" needs interactive: true in modal mode — ignored.');
+      }
+      return;
+    }
+    if (!found) return;
+    // setTimeout(0), not a microtask: React's root-delegated onClick runs
+    // after this native listener, and must finish first. The timer is NOT
+    // cleared on cleanup — the click itself commonly unmounts the target
+    // (navigation), which re-runs this effect before the timer fires.
+    const onClick = () => {
+      setTimeout(() => goNextRef.current(), 0);
+    };
+    found.addEventListener('click', onClick);
+    return () => found.removeEventListener('click', onClick);
+  }, [advanceOn, interactive, found, modal]);
+
+  // ---- Interactive-target elevation ----
+  // An interactive modal step's target stays clickable through the spotlight
+  // (see useFocusTrap above) — including opening its OWN floating surface
+  // (a DropdownMenu/Select/Popover trigger that is, or contains, the target).
+  // Mark it so useInOverlay's [data-tour-active-target] host elevates that
+  // surface above the tour instead of rendering it behind the card/scrim.
+  // Gated on !closing: once the tour starts closing the target is no longer
+  // being featured (mirrors the focus trap's own `!closing` gate).
+  useEffect(() => {
+    if (!(modal && interactive && found) || closing) return;
+    found.setAttribute('data-tour-active-target', '');
+    return () => found.removeAttribute('data-tour-active-target');
+  }, [modal, interactive, found, closing]);
+
+  // ---- Inert target (#697) ----
+  // A non-interactive modal step lights its target but must not let the
+  // pointer through to it (e.g. a lifted, open menu panel). Marker + global
+  // pointer-events rule instead of the `inert` attribute, which would also
+  // hide the panel from assistive tech. Keyboard is already contained: the
+  // focus trap only extends to the target on interactive steps.
+  useEffect(() => {
+    if (!(modal && !interactive && found) || closing) return;
+    found.setAttribute('data-tour-inert', '');
+    return () => found.removeAttribute('data-tour-inert');
+  }, [modal, interactive, found, closing]);
+
+  // ---- Current-target marker (#684) ----
+  // Every step's found target (modal or not, interactive or not) — floating
+  // surfaces read it via isTourHeld so the tour pointing into an open menu
+  // doesn't dismiss that menu when the user presses Next or the card takes
+  // focus. Separate from data-tour-active-target, which drives elevation.
+  useEffect(() => {
+    if (!found || closing) return;
+    found.setAttribute(TOUR_CURRENT_TARGET, '');
+    return () => found.removeAttribute(TOUR_CURRENT_TARGET);
+  }, [found, closing]);
+
+  // ---- Exit: unmount after the fade ----
+  useEffect(() => {
+    if (!closing) return;
+    const el = cardRef.current;
+    const onEnd = (e: TransitionEvent) => {
+      if (e.target === el) onExited();
+    };
+    el?.addEventListener('transitionend', onEnd);
+    const timer = setTimeout(onExited, EXIT_FALLBACK_MS);
+    return () => {
+      el?.removeEventListener('transitionend', onEnd);
+      clearTimeout(timer);
+    };
+  }, [closing, onExited]);
+
+  const onCardKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(e);
+    if (e.defaultPrevented) return;
+    if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return;
+    if ((e.target as HTMLElement).closest(EDITABLE)) return;
+    e.preventDefault();
+    if (e.key === 'ArrowLeft') goBack();
+    else if (!isLast) advance();
+  };
+
+  // Dev-only: an empty `steps` array or an out-of-range `step`/`defaultStep`.
+  // In an effect (not inline during render) so it fires once per bad
+  // index/total pair, not on every re-render, and stays above the early
+  // return below so hook order is stable.
+  useEffect(() => {
+    if (current) return;
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`[Tour] no step at index ${index} (steps: ${total}).`);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on index/total only, per design; `current` is derived from both
+  }, [index, total]);
+
+  if (!current) {
+    return null;
+  }
+
+  const state = closing ? 'closed' : 'open';
+  // No isPositioned-gated visibility hiding — same as Popover.Content, whose
+  // floatingStyles apply directly with no flash-prevention gate.
+  const cardStyle: CSSProperties = centered
+    ? { position: 'fixed', top: '50%', left: '50%', translate: '-50% -50%' }
+    : { ...floatingStyles, translate: '0 0' };
+  const arrowXY = middlewareData.arrow;
+
+  return createPortal(
+    // Single body child for ALL of Tour's portaled layers (spotlight, 4
+    // blockers, card) — Modal/Drawer's Overlay inerts every body child
+    // except ones matching their PORTAL_EXEMPT_SELECTOR, and that selector
+    // exempts by matching a body-direct child, not by descendant search.
+    // Wrapping means one `[data-tour-portal-root]` entry there exempts the
+    // whole tour, instead of Modal/Drawer inerting the card that the tour
+    // is trying to keep interactive. No class/style: children are already
+    // `position: fixed` inline, and an unstyled div creates no containing
+    // block or stacking context of its own.
+    <div data-tour-portal-root="">
+      {modal && (
+        <Spotlight
+          target={found}
+          padding={current.spotlightPadding ?? 8}
+          interactive={!!current.interactive && !!found}
+          state={state}
+          glide={glide}
+        />
+      )}
+      {/* {...rest} first so role / aria-* / tabIndex / data-state always win. */}
+      <div
+        {...rest}
+        ref={mergeRefs<HTMLDivElement>(cardRef, refs.setFloating, forwardedRef)}
+        role="dialog"
+        aria-modal={modal}
+        aria-labelledby={titleId}
+        aria-describedby={
+          [current.body != null && bodyId, clickToContinue && hintId].filter(Boolean).join(' ') ||
+          undefined
+        }
+        tabIndex={-1}
+        data-state={state}
+        data-side={centered ? undefined : resolvedSide}
+        data-centered={centered ? '' : undefined}
+        data-waiting={waiting ? '' : undefined}
+        data-glide={glide ? '' : undefined}
+        className={clsx(styles.card, className)}
+        style={{ ...style, ...cardStyle }}
+        onKeyDown={onCardKeyDown}
+      >
+        {!centered && (
+          <span
+            ref={arrowRef}
+            aria-hidden="true"
+            className={styles.arrow}
+            style={{
+              left: typeof arrowXY?.x === 'number' ? `${arrowXY.x}px` : undefined,
+              top: typeof arrowXY?.y === 'number' ? `${arrowXY.y}px` : undefined,
+              [staticSide]: 'calc(var(--tour-arrow-size) / -2)',
+            }}
+          />
+        )}
+        <Stack gap="md">
+          <Stack key={index} gap="xs" className={styles.content}>
+            <span className={styles.progress}>
+              {t('tour.progress', { current: index + 1, total })}
+            </span>
+            <h2 id={titleId} className={styles.title}>
+              {current.title}
+            </h2>
+            {current.body != null && (
+              <div id={bodyId} className={styles.body}>
+                {current.body}
+              </div>
+            )}
+          </Stack>
+          {clickToContinue && (
+            <span id={hintId} className={styles.hint}>
+              {t('tour.clickHint')}
+            </span>
+          )}
+          {/* Visual only: the status region below is the single announcement. */}
+          {waiting && (
+            <Cluster gap="sm" align="center" aria-hidden="true">
+              <CircularProgress size="sm" />
+              <span className={styles.waiting}>{t('tour.waiting')}</span>
+            </Cluster>
+          )}
+          <Cluster justify={isLast ? 'end' : 'between'} gap="sm">
+            {!isLast && (
+              <Button variant="ghost" size="sm" onClick={() => finish('skipped')}>
+                {t('tour.skip')}
+              </Button>
+            )}
+            <Cluster gap="sm">
+              {index > 0 && (
+                <Button variant="secondary" size="sm" onClick={goBack}>
+                  {t('tour.back')}
+                </Button>
+              )}
+              {/* Secondary on click-to-continue steps: the target is the primary action. */}
+              <Button
+                variant={clickToContinue ? 'secondary' : undefined}
+                size="sm"
+                // The advanceOn listener on the target advances; Next only clicks it.
+                onClick={advance}
+              >
+                {isLast ? doneLabel || t('tour.done') : t('tour.next')}
+              </Button>
+            </Cluster>
+          </Cluster>
+        </Stack>
+        {/* INSIDE the dialog on purpose — VoiceOver prunes content outside an
+            aria-modal dialog, so a region outside this div is never reached.
+            The dialog's name comes from aria-labelledby, so a plain child
+            span can't join it. Rendered unconditionally so only its text
+            mutates; same recipe as Switch's srOnly span otherwise. */}
+        <span role="status" aria-live="polite" className={styles.srOnly}>
+          {waitingText}
+        </span>
+      </div>
+    </div>,
+    document.body,
+  );
+});

package/src/components/Tour/index.ts

@@ -0,0 +1,2 @@
+export { Tour } from './Tour';
+export type { TourProps, TourStep, TourSide, TourAlign, TourFinishReason } from './Tour';