@robertlinde/react-tour-kit 0.8.8 → 1.0.0

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

@@ -0,0 +1,183 @@
+import type {ComponentType, ReactNode} from 'react';
+import type {TourPhase} from '../engine/tour-engine.js';
+import type {TooltipLayout} from '../geometry/compute-tooltip-layout.util.js';
+import type {Box, Point, Side, Size} from '../geometry/geometry.type.js';
+import type {TourPlacement} from '../types/tour-step.type.js';
+import type {ResolvedTheme} from '../utils/theme.util.js';
+
+/**
+ * How a platform draws the tour: primitives only. Every decision — what is visible, when and how
+ * things animate, which texts are shown, what a press means — is made by the shared overlay
+ * (`TourOverlay`) and default tooltip (`DefaultTooltip`), so all platforms behave the same.
+ *
+ * Every primitive is required: a platform that lacks one does not compile. A new feature either
+ * lives in the shared code (and every platform gets it), or needs a new primitive here (and every
+ * platform has to draw it).
+ */
+export type TourRenderer = {
+  /** The full-screen layer everything else is drawn in. */
+  readonly Layer: ComponentType<LayerProps>;
+  /** The area behind the spotlight that receives presses on the dimmed part of the screen. */
+  readonly Backdrop: ComponentType<BackdropProps>;
+  /** The dimmed overlay with a hole over the target. */
+  readonly Spotlight: ComponentType<SpotlightProps>;
+  /** Places the tooltip, plays its entrance, reports its size and takes focus. */
+  readonly TooltipFrame: ComponentType<TooltipFrameProps>;
+  /** Renders a tooltip invisibly with given size limits and reports its size. */
+  readonly MeasureFrame: ComponentType<MeasureFrameProps>;
+  /** The pieces of the built-in tooltip card. */
+  readonly card: CardParts;
+};
+
+/** What the user asked for through platform input (keys, gestures, system buttons). */
+export type TourIntent =
+  /** Go to the next step. */
+  | 'next'
+  /** Go to the previous step. */
+  | 'previous'
+  /** Leave the tour like Escape does (ends with `'escape'`). */
+  | 'escape'
+  /** Leave the tour with a system back action (ends with `'closed'`). */
+  | 'back';
+
+export type LayerProps = {
+  readonly children: ReactNode;
+  readonly state: TourPhase | 'closing';
+  /** Faded in (`true`) or out, over `fadeMs`. */
+  readonly isVisible: boolean;
+  readonly fadeMs: number;
+  /** False while fading out: input is no longer handled. */
+  readonly isInteractive: boolean;
+  readonly theme: ResolvedTheme;
+  /** Id of the element showing the step's title, `undefined` while no step is shown. */
+  readonly titleId: string | undefined;
+  /** Id of the element showing the step's content, `undefined` while no step is shown. */
+  readonly descriptionId: string | undefined;
+  /** Accessible name for when a custom tooltip renders no element with `titleId`. */
+  readonly fallbackLabel: string;
+  /** Text for screen readers when the step changes; empty when there is nothing to announce. */
+  readonly announcement: string;
+  /** Changes whenever a step is shown. */
+  readonly stepKey: number | undefined;
+  readonly onIntent: (intent: TourIntent) => void;
+};
+
+export type BackdropProps = {
+  /** Whether a press closes the tour (to show it with a pointer cursor, for example). */
+  readonly isDismissible: boolean;
+  /** A press on the dimmed area, at a point in layer coordinates. */
+  readonly onPress: (point: Point) => void;
+};
+
+export type SpotlightProps = {
+  /** The hole over the target, or `undefined`: no hole, everything dimmed (shrunk to the layer's centre). */
+  readonly hole: Box | undefined;
+  /** How changes are animated; `undefined`: applied instantly. */
+  readonly transition: SpotlightTransition | undefined;
+  readonly theme: ResolvedTheme;
+};
+
+export type SpotlightTransition = {
+  readonly durationMs: number;
+  readonly easing: 'standard' | 'linear';
+};
+
+export type TooltipFrameProps = {
+  readonly children: ReactNode;
+  readonly layout: TooltipLayout;
+  /** Played once, when the frame mounts. */
+  readonly entrance: Entrance;
+  /** A step change is being prepared: ignore presses. */
+  readonly isBusy: boolean;
+  /** The next target is being scrolled into view: hide the tooltip (keep its size). */
+  readonly isHidden: boolean;
+  readonly onSize: (size: Size) => void;
+  readonly onIntent: (intent: TourIntent) => void;
+};
+
+/** The tooltip's entrance: from this offset, scale and transparency to its place, after `delayMs`. */
+export type Entrance = {
+  readonly dx: number;
+  readonly dy: number;
+  readonly scale: number;
+  readonly durationMs: number;
+  readonly delayMs: number;
+};
+
+export type MeasureFrameProps = {
+  readonly children: ReactNode;
+  readonly maxWidth: number;
+  readonly maxHeight: number;
+  readonly onSize: (size: Size) => void;
+};
+
+/** The pieces of the built-in tooltip, put together by the shared `DefaultTooltip`. */
+export type CardParts = {
+  readonly Card: ComponentType<CardProps>;
+  readonly Arrow: ComponentType<ArrowProps>;
+  readonly Header: ComponentType<ContainerProps>;
+  readonly Counter: ComponentType<CounterProps>;
+  readonly CloseButton: ComponentType<CloseButtonProps>;
+  /** Scrolls when the content is taller than the space available. */
+  readonly Body: ComponentType<ContainerProps>;
+  readonly Title: ComponentType<TextPartProps>;
+  readonly Content: ComponentType<TextPartProps>;
+  readonly Footer: ComponentType<ContainerProps>;
+  readonly Button: ComponentType<ButtonProps>;
+  readonly Dots: ComponentType<DotsProps>;
+  readonly Dot: ComponentType<DotProps>;
+  readonly Ellipsis: ComponentType<EllipsisProps>;
+};
+
+export type CardProps = {
+  readonly placement: TourPlacement | 'center';
+  readonly children: ReactNode;
+};
+
+export type ArrowProps = {
+  readonly side: Side;
+  /** Distance from the card's left edge (top/bottom) or top edge (left/right) to the arrow's tip. */
+  readonly offset: number;
+};
+
+export type ContainerProps = {
+  readonly children: ReactNode;
+};
+
+export type CounterProps = {
+  readonly text: string;
+};
+
+export type CloseButtonProps = {
+  readonly label: string;
+  readonly onPress: () => void;
+};
+
+/** The title or the content: any React content, with the id screen readers find it by. */
+export type TextPartProps = {
+  readonly id: string;
+  readonly children: ReactNode;
+};
+
+export type ButtonProps = {
+  readonly kind: 'previous' | 'next';
+  readonly label: string;
+  readonly isDisabled: boolean;
+  readonly onPress: () => void;
+};
+
+export type DotsProps = {
+  /** Describes the group, for example "2 of 5". */
+  readonly label: string;
+  readonly children: ReactNode;
+};
+
+export type DotProps = {
+  readonly label: string;
+  readonly isCurrent: boolean;
+  readonly onPress: () => void;
+};
+
+export type EllipsisProps = {
+  readonly children?: never;
+};

package/src/shared/renderer/tooltip-model.ts

@@ -0,0 +1,44 @@
+import type {Side} from '../geometry/geometry.type.js';
+import type {TourTooltipProps} from '../types/tour-tooltip-props.type.js';
+import {getTruncatedDots} from '../utils/get-truncated-dots.util.js';
+import {formatTemplate, type ResolvedI18n} from '../utils/i18n.util.js';
+
+export type TooltipDot =
+  | {readonly kind: 'dot'; readonly index: number; readonly label: string; readonly isCurrent: boolean}
+  | {readonly kind: 'ellipsis'; readonly key: string};
+
+/** Everything the built-in tooltip shows, worked out once for every platform. */
+export type TooltipModel = {
+  readonly counter: string;
+  readonly closeLabel: string;
+  readonly arrow: {readonly side: Side; readonly offset: number} | undefined;
+  readonly previous: {readonly label: string; readonly isDisabled: boolean};
+  readonly next: {readonly label: string};
+  /** `undefined` for a single step. */
+  readonly dots: readonly TooltipDot[] | undefined;
+};
+
+export function tooltipModel(props: TourTooltipProps, i18n: ResolvedI18n): TooltipModel {
+  const {currentStep, totalSteps, placement, arrowOffset} = props;
+  const isLast = currentStep >= totalSteps - 1;
+  return {
+    counter: formatTemplate(i18n.stepCounterTemplate, {current: currentStep + 1, total: totalSteps}),
+    closeLabel: i18n.closeAriaLabel,
+    arrow: arrowOffset === undefined || placement === 'center' ? undefined : {side: placement, offset: arrowOffset},
+    previous: {label: i18n.prevLabel, isDisabled: currentStep === 0},
+    next: {label: isLast ? i18n.finishLabel : i18n.nextLabel},
+    dots:
+      totalSteps > 1
+        ? getTruncatedDots(currentStep, totalSteps).map((item): TooltipDot =>
+            item.type === 'ellipsis'
+              ? {kind: 'ellipsis', key: `ellipsis-${item.position}`}
+              : {
+                  kind: 'dot',
+                  index: item.index,
+                  label: formatTemplate(i18n.dotAriaLabelTemplate, {step: item.index + 1, total: totalSteps}),
+                  isCurrent: item.index === currentStep,
+                },
+          )
+        : undefined,
+  };
+}

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

@@ -0,0 +1,453 @@
+import {
+  type ComponentType,
+  isValidElement,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import {
+  type MeasureRequest,
+  type ShownStep,
+  type TourEngine,
+  tourLayout,
+  type TourViewState,
+} from '../engine/tour-engine.js';
+import {containsPoint, inflate} from '../geometry/box.util.js';
+import type {Box, Point, Size} from '../geometry/geometry.type.js';
+import {useTourView} from '../react/use-tour-view.hook.js';
+import type {TourTooltipProps} from '../types/tour-tooltip-props.type.js';
+import {formatTemplate, type ResolvedI18n} from '../utils/i18n.util.js';
+import type {ResolvedTheme} from '../utils/theme.util.js';
+import {entranceFor, fadeDuration, motion} from './motion.js';
+import {RendererContext, type RendererContextValue, TooltipLimitsContext} from './renderer-context.js';
+import type {SpotlightTransition, TourIntent, TourRenderer} from './renderer.type.js';
+
+export type TourOverlayProps = {
+  readonly engine: TourEngine;
+  readonly renderer: TourRenderer;
+  readonly theme: ResolvedTheme;
+  readonly i18n: ResolvedI18n;
+  readonly Tooltip: ComponentType<TourTooltipProps>;
+  readonly isOverlayDismissible: boolean;
+  readonly isReducedMotion: boolean;
+};
+
+function noop(): void {
+  // Intentionally empty.
+}
+
+/**
+ * The tour on screen, for every platform: decides what is visible, how it animates, what it
+ * says and what input means, and draws it with the platform's primitives ({@link TourRenderer}).
+ * Keeps the last step on screen while the tour fades out.
+ */
+export function TourOverlay(props: TourOverlayProps): ReactNode {
+  const view = useTourView(props.engine);
+  // When the tour ends, the last view stays on screen while it fades out. Worked out during render
+  // (not in an effect), so the overlay is never unmounted in between and the fade really plays.
+  const [tracked, setTracked] = useState<{view: TourViewState; closing: TourViewState | undefined}>(() => ({
+    view,
+    closing: undefined,
+  }));
+  let {closing} = tracked;
+  if (tracked.view !== view) {
+    const before = tracked.view;
+    closing = view.phase === 'idle' ? (before.phase === 'idle' ? closing : before) : undefined;
+    setTracked({view, closing});
+  }
+
+  const onClosed = useCallback((): void => {
+    setTracked((current) => ({...current, closing: undefined}));
+  }, []);
+  const isClosing = view.phase === 'idle' && closing !== undefined;
+  const rendered = view.phase === 'idle' ? closing : view;
+  return rendered ? <OverlayContent {...props} view={rendered} isClosing={isClosing} onClosed={onClosed} /> : null;
+}
+
+type OverlayContentProps = TourOverlayProps & {
+  readonly view: TourViewState;
+  readonly isClosing: boolean;
+  readonly onClosed: () => void;
+};
+
+function OverlayContent({
+  engine,
+  renderer,
+  theme,
+  i18n,
+  Tooltip,
+  isOverlayDismissible,
+  isReducedMotion,
+  view,
+  isClosing,
+  onClosed,
+}: OverlayContentProps): ReactNode {
+  const {Layer, Backdrop, Spotlight} = 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);
+  // 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;
+  if (isShowingSomething && !isClosing && !hasBeenVisible) {
+    setHasBeenVisible(true);
+  }
+
+  const isVisible = !isClosing && (isShowingSomething || hasBeenVisible);
+  // When the overlay became visible: presses on the dimmed area only count once it has faded in.
+  const visibleSince = useRef<number | undefined>(undefined);
+  useEffect(() => {
+    visibleSince.current = isVisible ? Date.now() : undefined;
+  }, [isVisible]);
+  const spotlight = useSpotlight(view, isVisible, isReducedMotion);
+  const announcement = useAnnouncement(shown, totalSteps, i18n, isClosing);
+
+  // Fade out, then unmount.
+  useEffect(() => {
+    if (!isClosing) {
+      return undefined;
+    }
+
+    const timer = setTimeout(onClosed, fadeDuration(true, isReducedMotion) + 20);
+    return (): void => {
+      clearTimeout(timer);
+    };
+  }, [isClosing, isReducedMotion, onClosed]);
+
+  const onIntent = useCallback(
+    (intent: TourIntent): void => {
+      if (isClosing) {
+        return;
+      }
+
+      switch (intent) {
+        case 'next': {
+          engine.actions.nextStep();
+          break;
+        }
+
+        case 'previous': {
+          engine.actions.prevStep();
+          break;
+        }
+
+        case 'escape': {
+          engine.dismiss('escape');
+          break;
+        }
+
+        case 'back': {
+          engine.dismiss('closed');
+          break;
+        }
+      }
+    },
+    [engine, isClosing],
+  );
+
+  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).
+    const since = visibleSince.current;
+    const hasFadedIn = since !== undefined && Date.now() - since >= motion.fadeInMs;
+    const isChangingStep = shown !== undefined && phase !== 'showing';
+    if (!isOverlayDismissible || isClosing || !hasFadedIn || isChangingStep) {
+      return;
+    }
+
+    // Presses on the highlighted element go nowhere; presses on the dimmed area close the tour.
+    if (spotlight.hole === undefined || !containsPoint(spotlight.hole, point)) {
+      engine.dismiss('blur');
+    }
+  };
+
+  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}>
+      <Layer
+        state={isClosing ? 'closing' : phase}
+        isVisible={isVisible}
+        fadeMs={fadeDuration(isClosing, isReducedMotion)}
+        isInteractive={!isClosing}
+        theme={theme}
+        titleId={shown ? titleId : undefined}
+        descriptionId={shown ? descriptionId : undefined}
+        fallbackLabel={(shown ? textOf(shown.step.title) : '') || counter}
+        announcement={announcement}
+        stepKey={shown?.transitionId}
+        onIntent={onIntent}
+      >
+        <Backdrop isDismissible={isOverlayDismissible} onPress={onBackdropPress} />
+        <Spotlight hole={spotlight.hole} transition={spotlight.transition} theme={theme} />
+        {shown ? (
+          <ShownTooltip
+            key={shown.transitionId}
+            engine={engine}
+            renderer={renderer}
+            Tooltip={Tooltip}
+            shown={shown}
+            totalSteps={totalSteps}
+            isBusy={phase === 'preparing' && !isClosing}
+            isHidden={phase === 'revealing'}
+            isDelayed={spotlight.isMorphing}
+            isReducedMotion={isReducedMotion}
+            titleId={titleId}
+            descriptionId={descriptionId}
+            onIntent={onIntent}
+          />
+        ) : null}
+        {measure && !isClosing ? (
+          <MeasuredTooltip
+            key={measure.id}
+            engine={engine}
+            renderer={renderer}
+            Tooltip={Tooltip}
+            request={measure}
+            totalSteps={totalSteps}
+          />
+        ) : null}
+      </Layer>
+    </RendererContext.Provider>
+  );
+}
+
+type ShownTooltipProps = {
+  readonly engine: TourEngine;
+  readonly renderer: TourRenderer;
+  readonly Tooltip: ComponentType<TourTooltipProps>;
+  readonly shown: ShownStep;
+  readonly totalSteps: number;
+  readonly isBusy: boolean;
+  readonly isHidden: boolean;
+  /** Enters a moment later, while the spotlight is still moving to the target. */
+  readonly isDelayed: boolean;
+  readonly isReducedMotion: boolean;
+  readonly titleId: string;
+  readonly descriptionId: string;
+  readonly onIntent: (intent: TourIntent) => void;
+};
+
+/** The step on screen: its tooltip in the platform's frame. Mounted once per shown step. */
+function ShownTooltip({
+  engine,
+  renderer,
+  Tooltip,
+  shown,
+  totalSteps,
+  isBusy,
+  isHidden,
+  isDelayed,
+  isReducedMotion,
+  titleId,
+  descriptionId,
+  onIntent,
+}: ShownTooltipProps): ReactNode {
+  const {TooltipFrame} = renderer;
+  const {transitionId, layout} = shown;
+  const onSize = useCallback(
+    (size: Size): void => {
+      engine.reportTooltipSize(transitionId, size);
+    },
+    [engine, transitionId],
+  );
+  const onClose = useCallback((): void => {
+    engine.dismiss('closed');
+  }, [engine]);
+  // The entrance is played once, when the step appears.
+  const [entrance] = useState(() => entranceFor(layout.placement, {isDelayed, isReducedMotion}));
+  return (
+    <TooltipFrame
+      layout={layout}
+      entrance={entrance}
+      isBusy={isBusy}
+      isHidden={isHidden}
+      onSize={onSize}
+      onIntent={onIntent}
+    >
+      <TooltipLimitsContext.Provider value={layout}>
+        <Tooltip
+          step={shown.step}
+          currentStep={shown.stepIndex}
+          totalSteps={totalSteps}
+          placement={layout.placement}
+          arrowOffset={layout.arrowOffset}
+          titleId={titleId}
+          descriptionId={descriptionId}
+          onNext={engine.actions.nextStep}
+          onPrev={engine.actions.prevStep}
+          onClose={onClose}
+          onGoToStep={engine.actions.goToStep}
+        />
+      </TooltipLimitsContext.Provider>
+    </TooltipFrame>
+  );
+}
+
+type MeasuredTooltipProps = {
+  readonly engine: TourEngine;
+  readonly renderer: TourRenderer;
+  readonly Tooltip: ComponentType<TourTooltipProps>;
+  readonly request: MeasureRequest;
+  readonly totalSteps: number;
+};
+
+/** The next step's tooltip, rendered invisibly with the same limits to learn its size: same content, no actions. */
+function MeasuredTooltip({engine, renderer, Tooltip, request, totalSteps}: MeasuredTooltipProps): ReactNode {
+  const {MeasureFrame} = renderer;
+  const id = useId();
+  const onSize = useCallback(
+    (size: Size): void => {
+      engine.reportTooltipSize(request.id, size);
+    },
+    [engine, request.id],
+  );
+  return (
+    <MeasureFrame maxWidth={request.maxWidth} maxHeight={request.maxHeight} onSize={onSize}>
+      <TooltipLimitsContext.Provider value={request}>
+        <Tooltip
+          step={request.step}
+          currentStep={request.stepIndex}
+          totalSteps={totalSteps}
+          placement={request.step.target === undefined ? 'center' : (request.step.placement ?? 'bottom')}
+          arrowOffset={undefined}
+          titleId={`${id}title`}
+          descriptionId={`${id}description`}
+          onNext={noop}
+          onPrev={noop}
+          onClose={noop}
+          onGoToStep={noop}
+        />
+      </TooltipLimitsContext.Provider>
+    </MeasureFrame>
+  );
+}
+
+/** 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);
+  const [wasWaiting, setWasWaiting] = useState(isWaiting);
+  if (wasWaiting !== isWaiting) {
+    setWasWaiting(isWaiting);
+    setIsDue(false);
+  }
+
+  useEffect(() => {
+    if (!isWaiting) {
+      return undefined;
+    }
+
+    const timer = setTimeout(() => {
+      setIsDue(true);
+    }, delayMs);
+    return (): void => {
+      clearTimeout(timer);
+    };
+  }, [isWaiting, delayMs]);
+  return isWaiting && isDue;
+}
+
+type SpotlightState = {
+  readonly hole: Box | undefined;
+  readonly transition: SpotlightTransition | undefined;
+  /** Moving to a new target right now (the tooltip waits a moment before entering). */
+  readonly isMorphing: boolean;
+};
+
+/**
+ * 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. Nothing animates before the overlay has appeared.
+ */
+function useSpotlight(view: TourViewState, isVisible: boolean, isReducedMotion: boolean): SpotlightState {
+  const {shown, phase, revealHighlight, 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'}`;
+
+  // The key at which the overlay appeared: it appears in place, later changes animate.
+  const [appearedAtKey, setAppearedAtKey] = useState<string | undefined>(undefined);
+  if (isVisible && appearedAtKey === undefined) {
+    setAppearedAtKey(key);
+  }
+
+  // A move to a new key keeps animating until it has had time to finish.
+  const [settledKey, setSettledKey] = useState(key);
+  useEffect(() => {
+    if (key === settledKey) {
+      return undefined;
+    }
+
+    const timer = setTimeout(() => {
+      setSettledKey(key);
+    }, motion.morphMs + 50);
+    return (): void => {
+      clearTimeout(timer);
+    };
+  }, [key, settledKey]);
+
+  const hasAppeared = appearedAtKey !== undefined;
+  const isMorphing = hasAppeared && key !== appearedAtKey && key !== settledKey;
+  let transition: SpotlightTransition | undefined;
+  if (hasAppeared && !isReducedMotion) {
+    if (isRevealing && followsScroll) {
+      transition = {durationMs: motion.chaseMs, easing: 'linear'};
+    } else if (isMorphing) {
+      transition = {durationMs: motion.morphMs, easing: 'standard'};
+    }
+  }
+
+  return {hole, transition, isMorphing};
+}
+
+/** "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 {
+  const [firstKey, setFirstKey] = useState<number | undefined>(undefined);
+  if (shown && firstKey === undefined) {
+    setFirstKey(shown.transitionId);
+  }
+
+  if (!shown || isClosing || shown.transitionId === firstKey) {
+    return '';
+  }
+
+  const counter = formatTemplate(i18n.stepCounterTemplate, {current: shown.stepIndex + 1, total: totalSteps});
+  const title = textOf(shown.step.title);
+  return title ? `${counter}: ${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') {
+    return String(node);
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((child: ReactNode) => textOf(child)).join('');
+  }
+
+  if (isValidElement<{children?: ReactNode}>(node)) {
+    return textOf(node.props.children);
+  }
+
+  return '';
+}

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

@@ -0,0 +1,23 @@
+import type {StartTourOptions} from './tour-end-info.type.js';
+import type {TourStep} from './tour-step.type.js';
+
+/** What `useTour()` returns. The functions keep their identity for the lifetime of the provider. */
+export type TourContextType = {
+  /** `true` from `startTour` until the tour ends. */
+  readonly isActive: boolean;
+  /** Zero-based index of the step on screen. */
+  readonly currentStep: number;
+  readonly steps: readonly TourStep[];
+  readonly currentTourId: string | undefined;
+  /**
+   * Starts a tour. Starting the tour that is already running (same id, or same steps array without
+   * an id) does nothing; starting a different one ends the current tour with the reason `'closed'`.
+   */
+  readonly startTour: (steps: readonly TourStep[], tourId?: string, options?: StartTourOptions) => void;
+  /** Ends the tour with the reason `'closed'`. */
+  readonly endTour: () => void;
+  /** Goes to the next step, or completes the tour on the last step. */
+  readonly nextStep: () => void;
+  readonly prevStep: () => void;
+  readonly goToStep: (index: number) => void;
+};