@robertlinde/react-tour-kit 1.0.3 → 1.1.1

package/dist/shared/utils/i18n.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.util.js","sourceRoot":"","sources":["../../../src/shared/utils/i18n.util.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,QAAQ;IACrB,mBAAmB,EAAE,sBAAsB;IAC3C,cAAc,EAAE,YAAY;IAC5B,oBAAoB,EAAE,mBAAmB;CAC1C,CAAC;AAEF,MAAM,QAAQ,GAAG;IACf,WAAW;IACX,WAAW;IACX,aAAa;IACb,qBAAqB;IACrB,gBAAgB;IAChB,sBAAsB;CAC0B,CAAC;AAEnD,MAAM,UAAU,WAAW,CAAC,IAA0B;IACpD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,QAAQ,GAAG,EAAC,GAAG,WAAW,EAAC,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,MAAiD;IAChG,OAAO,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CAChE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAC3D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"i18n.util.js","sourceRoot":"","sources":["../../../src/shared/utils/i18n.util.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,SAAS,EAAE,MAAM;IACjB,SAAS,EAAE,MAAM;IACjB,WAAW,EAAE,QAAQ;IACrB,mBAAmB,EAAE,sBAAsB;IAC3C,cAAc,EAAE,YAAY;IAC5B,oBAAoB,EAAE,mBAAmB;IACzC,gBAAgB,EAAE,UAAU;CAC7B,CAAC;AAEF,MAAM,QAAQ,GAAG;IACf,WAAW;IACX,WAAW;IACX,aAAa;IACb,qBAAqB;IACrB,gBAAgB;IAChB,sBAAsB;IACtB,kBAAkB;CAC8B,CAAC;AAEnD,MAAM,UAAU,WAAW,CAAC,IAA0B;IACpD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,QAAQ,GAAG,EAAC,GAAG,WAAW,EAAC,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,MAAiD;IAChG,OAAO,QAAQ,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE,CAChE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAC3D,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robertlinde/react-tour-kit",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "type": "module",
   "description": "Guided product tours for React and React Native. Smooth, accessible, and guaranteed to stay on screen: the target is scrolled into view and the tooltip never renders out of sight.",
   "author": "Robert Linde",
@@ -50,7 +50,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
-    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.tooling.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.tooling.json && tsc -p scripts",
     "lint": "xo --ignore \"demos/**\"",
     "lint:fix": "xo --fix --ignore \"demos/**\"",
     "format": "prettier --write .",
@@ -64,6 +64,8 @@
     "check:package": "publint --strict && attw --pack . --profile esm-only",
     "smoke:node": "node test/smoke-node.mjs",
     "demo:web": "npm run dev --prefix demos/react",
+    "demo:showcase": "npm run showcase --prefix demos/react",
+    "demo:record": "node scripts/record-demo.ts",
     "demo:ios": "npm run ios --prefix demos/react-native",
     "demo:android": "npm run android --prefix demos/react-native",
     "prepare": "husky || true"

package/src/react-native-platform/layer/native-renderer.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react';
 import {
   AccessibilityInfo,
+  ActivityIndicator,
   Animated,
   BackHandler,
   Easing,
@@ -46,6 +47,7 @@ import type {
   TextPartProps,
   TooltipFrameProps,
   TourRenderer,
+  WaitingProps,
 } from '../../shared/renderer/renderer.type.js';
 
 const emptySize: Size = {width: 0, height: 0};
@@ -512,6 +514,36 @@ function TooltipFrame({children, layout, entrance, isBusy, isHidden, onSize, onI
   );
 }
 
+/** A spinner in the middle of the layer, faded in on the UI thread; presses go through to the dimmed area. */
+function Waiting({label, theme}: WaitingProps): ReactNode {
+  const [opacity] = useState(() => new Animated.Value(0));
+  useEffect(() => {
+    const animation = Animated.timing(opacity, {
+      toValue: 1,
+      duration: motion.fadeInMs,
+      easing: standardEasing,
+      useNativeDriver,
+    });
+    animation.start();
+    return (): void => {
+      animation.stop();
+    };
+  }, [opacity]);
+
+  return (
+    <View pointerEvents="none" style={[StyleSheet.absoluteFill, styles.waitingLayer]}>
+      <Animated.View
+        accessible
+        accessibilityRole="progressbar"
+        accessibilityLabel={label}
+        style={[styles.card, styles.waitingCard, {backgroundColor: theme.tooltipBackground, opacity}]}
+      >
+        <ActivityIndicator color={theme.primaryColor} />
+      </Animated.View>
+    </View>
+  );
+}
+
 function MeasureFrame({children, maxWidth, maxHeight, onSize}: MeasureFrameProps): ReactNode {
   return (
     <View
@@ -728,7 +760,7 @@ const card: CardParts = {
 };
 
 /** How React Native draws the tour. */
-export const nativeRenderer: TourRenderer = {Layer, Backdrop, Spotlight, TooltipFrame, MeasureFrame, card};
+export const nativeRenderer: TourRenderer = {Layer, Backdrop, Spotlight, TooltipFrame, MeasureFrame, Waiting, card};
 
 const styles = StyleSheet.create({
   piece: {position: 'absolute', top: 0, left: 0},
@@ -737,6 +769,8 @@ const styles = StyleSheet.create({
   verticalBar: {width: ringWidth, height: barLength},
   hidden: {opacity: 0},
   measure: {position: 'absolute', top: 0, left: 0, opacity: 0},
+  waitingLayer: {alignItems: 'center', justifyContent: 'center'},
+  waitingCard: {width: 56, height: 56, alignItems: 'center', justifyContent: 'center'},
   card: {
     borderRadius: 14,
     ...Platform.select({

package/src/react-platform/layer/styles.ts

@@ -252,9 +252,49 @@ export const tourCss = `
   }
 }
 
+/* While a step takes a while to prepare: a spinner in the middle, on the tooltip's background. */
+.rtk-waiting {
+  position: fixed !important;
+  top: 50% !important;
+  left: 50% !important;
+  translate: -50% -50%;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 56px;
+  height: 56px;
+  margin: 0 !important;
+  border-radius: var(--rtk-radius);
+  background: var(--rtk-bg);
+  box-shadow: 0 12px 32px -8px rgba(15, 23, 42, 0.35), 0 4px 12px -6px rgba(15, 23, 42, 0.2);
+  pointer-events: none !important;
+  animation: rtk-fade-in var(--rtk-fade-duration, 200ms) var(--rtk-ease) both;
+}
+.rtk-spinner {
+  box-sizing: border-box;
+  width: 24px;
+  height: 24px;
+  border: 3px solid rgba(127, 127, 127, 0.25);
+  border: 3px solid color-mix(in srgb, var(--rtk-primary) 20%, transparent);
+  border-top-color: var(--rtk-primary);
+  border-radius: 50%;
+  animation: rtk-spin 0.8s linear infinite;
+}
+@keyframes rtk-fade-in {
+  from { opacity: 0; }
+}
+@keyframes rtk-spin {
+  to { rotate: 1turn; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .rtk-spinner { animation-duration: 2s; }
+}
+
 @media (forced-colors: active) {
   .rtk-spotlight { outline: 3px solid Highlight; }
-  .rtk-card { border: 1px solid CanvasText; }
+  .rtk-card, .rtk-waiting { border: 1px solid CanvasText; }
+  .rtk-spinner { border-color: GrayText; border-top-color: Highlight; }
   /* Without backgrounds, a border is what shows a button is one. */
   .rtk-button { border: 1px solid ButtonText !important; }
   .rtk-button:disabled { border-color: GrayText !important; }

package/src/react-platform/layer/web-renderer.tsx

@@ -28,6 +28,7 @@ import type {
   TextPartProps,
   TooltipFrameProps,
   TourRenderer,
+  WaitingProps,
 } from '../../shared/renderer/renderer.type.js';
 import {handlesKey, pageDirection} from '../dom/elements.util.js';
 import {keepReachable} from '../dom/keep-reachable.util.js';
@@ -473,6 +474,15 @@ function TooltipFrame({children, layout, entrance, isBusy, isHidden, onSize}: To
   );
 }
 
+/** A spinner in the middle of the screen; presses go through to the dimmed area. */
+function Waiting({label}: WaitingProps): ReactNode {
+  return (
+    <div className="rtk-waiting" role="progressbar" aria-label={label}>
+      <span aria-hidden="true" className="rtk-spinner" />
+    </div>
+  );
+}
+
 function MeasureFrame({children, maxWidth, maxHeight, onSize}: MeasureFrameProps): ReactNode {
   const ref = useRef<HTMLDivElement | null>(null);
   useIsomorphicLayoutEffect(() => {
@@ -611,4 +621,4 @@ const card: CardParts = {
 };
 
 /** How the web draws the tour. */
-export const webRenderer: TourRenderer = {Layer, Backdrop, Spotlight, TooltipFrame, MeasureFrame, card};
+export const webRenderer: TourRenderer = {Layer, Backdrop, Spotlight, TooltipFrame, MeasureFrame, Waiting, card};

package/src/shared/engine/tour-engine.ts

@@ -96,6 +96,11 @@ export type TourViewState = {
   readonly tourKey: number;
   readonly steps: readonly TourStep[];
   readonly shown: ShownStep | undefined;
+  /**
+   * While the next step is prepared: the shown step's target has gone (the app moved on, for example
+   * `onBeforeStep` navigated), so the shown step must not stay on screen.
+   */
+  readonly isShownTargetGone: boolean;
   readonly measure: MeasureRequest | undefined;
 };
 
@@ -140,6 +145,8 @@ type State = {
   readonly currentStep: number;
   readonly pendingStepIndex: number | undefined;
   readonly shown: ShownStep | undefined;
+  /** See {@link TourViewState.isShownTargetGone}. */
+  readonly isShownTargetGone: boolean;
   readonly measure: MeasureRequest | undefined;
   /** Where the target being revealed currently is (only meaningful while revealing). */
   readonly revealHighlight: Box | undefined;
@@ -228,6 +235,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
     currentStep: 0,
     pendingStepIndex: undefined,
     shown: undefined,
+    isShownTargetGone: false,
     measure: undefined,
     revealHighlight: undefined,
   };
@@ -239,6 +247,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
     tourKey: 0,
     steps: emptySteps,
     shown: undefined,
+    isShownTargetGone: false,
     measure: undefined,
   };
 
@@ -248,6 +257,8 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
   let transition: AbortController | undefined;
   /** Observation of the step on screen. */
   let stepScope: AbortController | undefined;
+  /** While the next step is prepared: watching whether the step on screen's target goes away. */
+  let goneScope: AbortController | undefined;
   let shownDetails: ShownDetails | undefined;
   let measureSequence = 0;
   /** A scroll that brings the shown target back into view is running. */
@@ -290,6 +301,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
       tourKey: state.session?.key ?? previous.tourKey,
       steps: state.session?.steps ?? emptySteps,
       shown: state.shown,
+      isShownTargetGone: state.isShownTargetGone,
       measure: state.measure,
     };
     const isUnchanged =
@@ -299,6 +311,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
       next.tourKey === previous.tourKey &&
       next.steps === previous.steps &&
       next.shown === previous.shown &&
+      next.isShownTargetGone === previous.isShownTargetGone &&
       next.measure === previous.measure;
     return isUnchanged ? previous : next;
   }
@@ -573,9 +586,43 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
     keepInViewScope = undefined;
     const controller = new AbortController();
     transition = controller;
+    watchShownTarget().catch(reportError);
     return controller;
   }
 
+  /**
+   * While the next step is prepared, the step on screen stays (a quick step change shows nothing in
+   * between) and follows its target. Once that target is gone, though, the app has moved on (for
+   * example `onBeforeStep` navigated), and the step must not stay over what is there now.
+   */
+  async function watchShownTarget(): Promise<void> {
+    goneScope?.abort();
+    const {shown} = state;
+    const target = shown?.step.target;
+    if (!shown || target === undefined || state.isShownTargetGone) {
+      return;
+    }
+
+    const scope = new AbortController();
+    goneScope = scope;
+    let last = shownDetails?.measurement;
+    while (!scope.signal.aborted) {
+      // eslint-disable-next-line no-await-in-loop -- one change at a time
+      const current = await options.adapter.waitForMove(target, last, scope.signal);
+      if (scope.signal.aborted || state.shown !== shown) {
+        return;
+      }
+
+      if (!current) {
+        setState({isShownTargetGone: true});
+        return;
+      }
+
+      last = current;
+      void remeasure(scope.signal);
+    }
+  }
+
   /**
    * Prepares the steps from `requested` on, in the direction of travel, until one can be shown.
    * Steps whose target cannot be found or brought into view are skipped.
@@ -744,6 +791,8 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
       transition = undefined;
     }
 
+    goneScope?.abort();
+    goneScope = undefined;
     shownDetails = {measurement, size};
     lastTooltipSize = size;
     const highlight = measurement ? highlightOf(measurement) : undefined;
@@ -752,6 +801,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
       currentStep: index,
       pendingStepIndex: undefined,
       measure: undefined,
+      isShownTargetGone: false,
       shown: {
         transitionId: id,
         stepIndex: index,
@@ -952,6 +1002,8 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
     transition = undefined;
     stepScope?.abort();
     stepScope = undefined;
+    goneScope?.abort();
+    goneScope = undefined;
     shownDetails = undefined;
     for (const resolve of sizeWaiters.values()) {
       resolve(lastTooltipSize ?? fallbackTooltipSize);
@@ -966,6 +1018,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
       currentStep: 0,
       pendingStepIndex: undefined,
       shown: undefined,
+      isShownTargetGone: false,
       measure: undefined,
     });
     safeInvoke(() => session.onTourEnd?.(session.tourId, info));
@@ -1015,6 +1068,7 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
         currentStep: 0,
         pendingStepIndex: 0,
         shown: undefined,
+        isShownTargetGone: false,
         measure: undefined,
       });
       void prepare(0, 1);
@@ -1083,6 +1137,8 @@ export function createTourEngine(initialOptions: TourEngineOptions): TourEngine
     transition = undefined;
     stepScope?.abort();
     stepScope = undefined;
+    goneScope?.abort();
+    goneScope = undefined;
   }
 
   function resume(): void {

package/src/shared/renderer/motion.ts

@@ -17,8 +17,11 @@ export const motion = {
   /** Distance (from the target's side) and scale the tooltip enters from. */
   enterOffset: 6,
   enterScale: 0.96,
-  /** If the first step takes longer than this to prepare (navigation, data), the screen is dimmed meanwhile. */
-  waitingDimDelayMs: 300,
+  /**
+   * If a step takes longer than this to prepare (navigation, data, a target that is still
+   * rendering), the tour shows that it is waiting: the highlight closes and a spinner appears.
+   */
+  waitingDelayMs: 300,
   /** Control points of the standard easing curve (`cubic-bezier`). */
   easing: [0.2, 0, 0, 1],
 } as const;

package/src/shared/renderer/renderer.type.ts

@@ -25,6 +25,8 @@ export type TourRenderer = {
   readonly TooltipFrame: ComponentType<TooltipFrameProps>;
   /** Renders a tooltip invisibly with given size limits and reports its size. */
   readonly MeasureFrame: ComponentType<MeasureFrameProps>;
+  /** A spinner in the middle of the layer, while the tour waits for a step that takes a while to prepare. */
+  readonly Waiting: ComponentType<WaitingProps>;
   /** The pieces of the built-in tooltip card. */
   readonly card: CardParts;
 };
@@ -104,6 +106,12 @@ export type Entrance = {
   readonly delayMs: number;
 };
 
+export type WaitingProps = {
+  /** Accessible name of the spinner. */
+  readonly label: string;
+  readonly theme: ResolvedTheme;
+};
+
 export type MeasureFrameProps = {
   readonly children: ReactNode;
   readonly maxWidth: number;

package/src/shared/renderer/tour-overlay.tsx

@@ -86,14 +86,15 @@ function OverlayContent({
   isClosing,
   onClosed,
 }: OverlayContentProps): ReactNode {
-  const {Layer, Backdrop, Spotlight} = renderer;
+  const {Layer, Backdrop, Spotlight, Waiting} = renderer;
   const id = useId();
   const titleId = `${id}title`;
   const descriptionId = `${id}description`;
   const {shown, phase, measure} = view;
   const totalSteps = view.steps.length;
   // The first step can take a while (navigation in onBeforeStep): dim the screen after a moment.
-  const isWaitingDimmed = useDelayedFlag(!shown && !isClosing, motion.waitingDimDelayMs);
+  const isWaitingDimmed = useDelayedFlag(!shown && !isClosing, motion.waitingDelayMs);
+  const {isPreparing, isWaiting, isShownGone} = usePreparation(view, isClosing);
   // Once on screen, the overlay stays until the tour ends (also when another tour takes over).
   const [hasBeenVisible, setHasBeenVisible] = useState(false);
   const isShowingSomething = shown !== undefined || isWaitingDimmed;
@@ -107,8 +108,8 @@ function OverlayContent({
   useEffect(() => {
     visibleSince.current = isVisible ? Date.now() : undefined;
   }, [isVisible]);
-  const spotlight = useSpotlight(view, isVisible, isReducedMotion);
-  const announcement = useAnnouncement(shown, totalSteps, i18n, isClosing);
+  const spotlight = useSpotlight(view, isVisible, isReducedMotion, isWaiting || isShownGone);
+  const announcement = useAnnouncement(view, i18n, isClosing, isWaiting);
 
   // Fade out, then unmount.
   useEffect(() => {
@@ -155,10 +156,11 @@ function OverlayContent({
 
   const onBackdropPress = (point: Point): void => {
     // Not while the overlay is still appearing (a double click on the button that started the
-    // tour), nor while a step change is under way (a second tap on Next falls through the busy tooltip).
+    // tour), nor right after a step change began (a second tap on Next falls through the busy
+    // tooltip). Once the tour shows that it is waiting, a press leaves it.
     const since = visibleSince.current;
     const hasFadedIn = since !== undefined && Date.now() - since >= motion.fadeInMs;
-    const isChangingStep = shown !== undefined && phase !== 'showing';
+    const isChangingStep = shown !== undefined && phase !== 'showing' && !isWaiting;
     if (!isOverlayDismissible || isClosing || !hasFadedIn || isChangingStep) {
       return;
     }
@@ -170,9 +172,6 @@ function OverlayContent({
   };
 
   const context = useMemo<RendererContextValue>(() => ({renderer, theme, i18n}), [renderer, theme, i18n]);
-  const counter = shown
-    ? formatTemplate(i18n.stepCounterTemplate, {current: shown.stepIndex + 1, total: totalSteps})
-    : '';
 
   return (
     <RendererContext.Provider value={context}>
@@ -184,7 +183,7 @@ function OverlayContent({
         theme={theme}
         titleId={shown ? titleId : undefined}
         descriptionId={shown ? descriptionId : undefined}
-        fallbackLabel={(shown ? textOf(shown.step.title) : '') || counter}
+        fallbackLabel={fallbackLabelOf(shown, totalSteps, i18n)}
         announcement={announcement}
         stepKey={shown?.transitionId}
         onIntent={onIntent}
@@ -199,8 +198,8 @@ function OverlayContent({
             Tooltip={Tooltip}
             shown={shown}
             totalSteps={totalSteps}
-            isBusy={phase === 'preparing' && !isClosing}
-            isHidden={phase === 'revealing'}
+            isBusy={isPreparing}
+            isHidden={phase === 'revealing' || isWaiting || isShownGone}
             isDelayed={spotlight.isMorphing}
             isReducedMotion={isReducedMotion}
             titleId={titleId}
@@ -208,6 +207,7 @@ function OverlayContent({
             onIntent={onIntent}
           />
         ) : null}
+        {isWaiting ? <Waiting label={i18n.loadingAriaLabel} theme={theme} /> : null}
         {measure && !isClosing ? (
           <MeasuredTooltip
             key={measure.id}
@@ -334,6 +334,21 @@ function MeasuredTooltip({engine, renderer, Tooltip, request, totalSteps}: Measu
   );
 }
 
+/**
+ * While the next step is prepared. Preparing it takes a while (`isWaiting`): the highlight closes and
+ * a spinner shows that the tour is waiting. The app moved on before the next step is ready (the step
+ * on screen's target is gone, `isShownGone`): the step goes at once rather than stay over what is
+ * there now, and the spinner still waits for its delay.
+ */
+function usePreparation(
+  view: TourViewState,
+  isClosing: boolean,
+): {readonly isPreparing: boolean; readonly isWaiting: boolean; readonly isShownGone: boolean} {
+  const isPreparing = view.phase === 'preparing' && !isClosing;
+  const isWaiting = useDelayedFlag(isPreparing, motion.waitingDelayMs);
+  return {isPreparing, isWaiting, isShownGone: isPreparing && view.isShownTargetGone};
+}
+
 /** True once `isWaiting` has been true for `delayMs`, as long as it stays true. */
 function useDelayedFlag(isWaiting: boolean, delayMs: number): boolean {
   const [isDue, setIsDue] = useState(false);
@@ -365,20 +380,46 @@ type SpotlightState = {
   readonly isMorphing: boolean;
 };
 
+/** What the spotlight marks, and the key under which a move there is animated. */
+function spotlightTarget(
+  view: TourViewState,
+  isWaiting: boolean,
+): {readonly hole: Box | undefined; readonly key: string} {
+  const {shown, phase, revealHighlight} = view;
+  const shownKey = shown?.transitionId ?? 'none';
+  // While the tour waits for a step, nothing is highlighted: the hole closes.
+  if (isWaiting) {
+    return {hole: undefined, key: `waiting:${shownKey}`};
+  }
+
+  if (phase === 'revealing') {
+    return {
+      hole: revealHighlight ? inflate(revealHighlight, tourLayout.highlightPadding) : undefined,
+      key: `reveal:${shownKey}`,
+    };
+  }
+
+  const hole = shown?.highlight ? inflate(shown.highlight, tourLayout.highlightPadding) : undefined;
+  return {hole, key: `${shownKey}:${hole ? 'open' : 'closed'}`};
+}
+
 /**
  * Where the spotlight's hole is and how it gets there. While the next target is scrolled into
  * view, the hole goes with it (frame by frame, or straight to where it will end up); otherwise it
  * marks the step on screen. Moving to another step is animated; following a target that moves on
  * its own (layout changes, resizing) is instant, like the tooltip, also while the spotlight is
- * still on its way. Nothing animates before the overlay has appeared.
+ * still on its way. While the tour waits for a step, the hole closes. Nothing animates before the
+ * overlay has appeared.
  */
-function useSpotlight(view: TourViewState, isVisible: boolean, isReducedMotion: boolean): SpotlightState {
-  const {shown, phase, revealHighlight, followsScroll} = view;
+function useSpotlight(
+  view: TourViewState,
+  isVisible: boolean,
+  isReducedMotion: boolean,
+  isWaiting: boolean,
+): SpotlightState {
+  const {phase, followsScroll} = view;
   const isRevealing = phase === 'revealing';
-  const source = isRevealing ? revealHighlight : shown?.highlight;
-  const hole = source ? inflate(source, tourLayout.highlightPadding) : undefined;
-  const shownKey = shown?.transitionId ?? 'none';
-  const key = isRevealing ? `reveal:${shownKey}` : `${shownKey}:${hole ? 'open' : 'closed'}`;
+  const {hole, key} = spotlightTarget(view, isWaiting);
 
   // The key at which the overlay appeared: it appears in place, later changes animate.
   const [appearedAtKey, setAppearedAtKey] = useState<string | undefined>(undefined);
@@ -409,26 +450,37 @@ function useSpotlight(view: TourViewState, isVisible: boolean, isReducedMotion:
 }
 
 /** "2 of 5: Title" when the step changes (the first step is announced by the tour appearing). */
-function useAnnouncement(
-  shown: ShownStep | undefined,
-  totalSteps: number,
-  i18n: ResolvedI18n,
-  isClosing: boolean,
-): string {
+function useAnnouncement(view: TourViewState, i18n: ResolvedI18n, isClosing: boolean, isWaiting: boolean): string {
+  const {shown, phase} = view;
   const [firstKey, setFirstKey] = useState<number | undefined>(undefined);
   if (shown && firstKey === undefined) {
     setFirstKey(shown.transitionId);
   }
 
-  if (!shown || isClosing || shown.transitionId === firstKey) {
+  // While the tour waits for a step, that is what is said; a step once it is on screen.
+  if (isWaiting) {
+    return i18n.loadingAriaLabel;
+  }
+
+  if (!shown || isClosing || phase !== 'showing' || shown.transitionId === firstKey) {
     return '';
   }
 
-  const counter = formatTemplate(i18n.stepCounterTemplate, {current: shown.stepIndex + 1, total: totalSteps});
+  const counter = formatTemplate(i18n.stepCounterTemplate, {current: shown.stepIndex + 1, total: view.steps.length});
   const title = textOf(shown.step.title);
   return title ? `${counter}: ${title}` : counter;
 }
 
+/** Name of the tour dialog for a custom tooltip without a title element: the step's title, or its counter. */
+function fallbackLabelOf(shown: ShownStep | undefined, totalSteps: number, i18n: ResolvedI18n): string {
+  if (!shown) {
+    return '';
+  }
+
+  const counter = formatTemplate(i18n.stepCounterTemplate, {current: shown.stepIndex + 1, total: totalSteps});
+  return textOf(shown.step.title) || counter;
+}
+
 /** The plain text of React content (strings, numbers, arrays and the children of elements). */
 export function textOf(node: ReactNode): string {
   if (typeof node === 'string' || typeof node === 'number') {

package/src/shared/types/tour-i18n.type.ts

@@ -1,4 +1,4 @@
-/** Texts of the built-in tooltip. Every key is optional. */
+/** Texts of the tour (most of them in the built-in tooltip). Every key is optional. */
 export type TourI18n = {
   /** @defaultValue `'Next'` */
   readonly nextLabel?: string;
@@ -12,4 +12,6 @@ export type TourI18n = {
   readonly closeAriaLabel?: string;
   /** Accessible name of each step dot; `{step}` and `{total}` are replaced. @defaultValue `'Go to step {step}'` */
   readonly dotAriaLabelTemplate?: string;
+  /** Accessible name of the spinner shown while a step takes a while to prepare. @defaultValue `'Loading…'` */
+  readonly loadingAriaLabel?: string;
 };

package/src/shared/utils/i18n.util.ts

@@ -9,6 +9,7 @@ export const defaultI18n: ResolvedI18n = {
   stepCounterTemplate: '{current} of {total}',
   closeAriaLabel: 'Close tour',
   dotAriaLabelTemplate: 'Go to step {step}',
+  loadingAriaLabel: 'Loading…',
 };
 
 const i18nKeys = [
@@ -18,6 +19,7 @@ const i18nKeys = [
   'stepCounterTemplate',
   'closeAriaLabel',
   'dotAriaLabelTemplate',
+  'loadingAriaLabel',
 ] as const satisfies ReadonlyArray<keyof TourI18n>;
 
 export function resolveI18n(i18n: TourI18n | undefined): ResolvedI18n {