@robertlinde/react-tour-kit 1.0.2 → 1.1.0

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,8 +28,10 @@ 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';
 import {lockScroll} from '../dom/scroll-lock.util.js';
 import {injectTourStyles} from './styles.js';
 
@@ -154,7 +156,9 @@ function Layer({
     const trigger = document.activeElement;
     openModal(dialog);
     const unlock = lockScroll(dialog);
+    const stopKeepingReachable = keepReachable(dialog);
     return (): void => {
+      stopKeepingReachable();
       unlock();
       reopening.current = true;
       closeModal(dialog);
@@ -162,6 +166,29 @@ function Layer({
     };
   }, []);
 
+  // Escape belongs to the topmost modal, the tour. Modal libraries underneath listen for it on the
+  // document before it reaches the tour (Radix, in the capture phase): take it on the window first.
+  useEffect(() => {
+    if (!isInteractive) {
+      return undefined;
+    }
+
+    const onEscape = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape' || event.isComposing || event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+
+      event.stopPropagation();
+      event.preventDefault();
+      onIntent('escape');
+    };
+
+    globalThis.addEventListener('keydown', onEscape, {capture: true});
+    return (): void => {
+      globalThis.removeEventListener('keydown', onEscape, {capture: true});
+    };
+  }, [isInteractive, onIntent]);
+
   // If the app opened its own modal (in onBeforeStep), move the tour back on top of it.
   useEffect(() => {
     const dialog = layerRef.current;
@@ -229,12 +256,6 @@ function Layer({
       return;
     }
 
-    if (key === 'Escape') {
-      event.preventDefault();
-      onIntent('escape');
-      return;
-    }
-
     if ((key === 'ArrowRight' || key === 'ArrowLeft') && !handlesKey(event.target, key)) {
       event.preventDefault();
       // In right-to-left pages, the arrow pointing to the start goes forward.
@@ -453,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(() => {
@@ -591,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/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,17 @@ 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);
+  // Preparing a step takes a while: the highlight closes and a spinner shows that the tour is waiting.
+  const isPreparing = phase === 'preparing' && !isClosing;
+  const isWaiting = useDelayedFlag(isPreparing, motion.waitingDelayMs);
   // 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 +110,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);
+  const announcement = useAnnouncement(view, i18n, isClosing, isWaiting);
 
   // Fade out, then unmount.
   useEffect(() => {
@@ -155,10 +158,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 +174,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 +185,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 +200,8 @@ function OverlayContent({
             Tooltip={Tooltip}
             shown={shown}
             totalSteps={totalSteps}
-            isBusy={phase === 'preparing' && !isClosing}
-            isHidden={phase === 'revealing'}
+            isBusy={isPreparing}
+            isHidden={phase === 'revealing' || isWaiting}
             isDelayed={spotlight.isMorphing}
             isReducedMotion={isReducedMotion}
             titleId={titleId}
@@ -208,6 +209,7 @@ function OverlayContent({
             onIntent={onIntent}
           />
         ) : null}
+        {isWaiting ? <Waiting label={i18n.loadingAriaLabel} theme={theme} /> : null}
         {measure && !isClosing ? (
           <MeasuredTooltip
             key={measure.id}
@@ -365,20 +367,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 +437,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 {