@robertlinde/react-tour-kit 0.8.8 → 1.0.0

package/src/shared/platform/create-tour-adapter.ts

@@ -0,0 +1,151 @@
+import {nextFrame, nextFrameOrAfter} from '../engine/abort.util.js';
+import type {TargetMeasurement, TourAdapter} from '../engine/tour-adapter.type.js';
+import {boxesEqual} from '../geometry/box.util.js';
+import type {Box} from '../geometry/geometry.type.js';
+import type {TourTarget} from '../types/tour-step.type.js';
+import {requestFrame} from '../utils/frame.util.js';
+import type {PlatformAdapter} from './platform.type.js';
+import {revealInScrollContainers} from './reveal-in-scroll-containers.js';
+
+/** A found target counts as settled once it has not moved for this many frames (screens slide in, drawers expand)... */
+const stableFramesNeeded = 2;
+/** ...or after this many frames, so a target that never stops moving (a pulsing button) is still shown... */
+const maxSettleFrames = 12;
+/** ...or after this long: frames stop in background tabs, timers only slow down. */
+const maxSettleMs = 300;
+/** Longest wait for a frame while settling, for the same reason. */
+const settleFrameMs = 50;
+
+/**
+ * The tour's behaviour on top of a platform: waiting for targets, following them, and scrolling
+ * them into view. Shared by every platform, so they behave the same; platforms only provide the
+ * raw facts ({@link PlatformAdapter}).
+ */
+export function createTourAdapter(platform: PlatformAdapter): TourAdapter {
+  return {
+    measure: platform.measure,
+
+    async waitForTarget(target, signal): Promise<TargetMeasurement | undefined> {
+      // Subscribed for the whole wait, so a change between measuring and waiting is never missed.
+      let hasChanged = false;
+      let wake: (() => void) | undefined;
+      const unsubscribe = platform.subscribe(target, () => {
+        hasChanged = true;
+        wake?.();
+      });
+      const onAbort = (): void => {
+        wake?.();
+      };
+
+      const sleepUntilChange = async (): Promise<void> =>
+        new Promise<void>((resolve) => {
+          wake = resolve;
+        });
+      signal.addEventListener('abort', onAbort);
+      try {
+        let previous: Box | undefined;
+        let stableFrames = 0;
+        let settleFrames = 0;
+        let firstSeenAt = 0;
+        while (!signal.aborted) {
+          hasChanged = false;
+          // eslint-disable-next-line no-await-in-loop -- measuring until the target is there and settled
+          const current = await platform.measure(target);
+          if (signal.aborted) {
+            return undefined;
+          }
+
+          if (current) {
+            stableFrames = previous && boxesEqual(current.rect, previous, 0.5) ? stableFrames + 1 : 0;
+            firstSeenAt = settleFrames === 0 ? Date.now() : firstSeenAt;
+            settleFrames++;
+            const isSettled =
+              stableFrames >= stableFramesNeeded ||
+              settleFrames > maxSettleFrames ||
+              Date.now() - firstSeenAt >= maxSettleMs;
+            if (isSettled) {
+              return current;
+            }
+
+            previous = current.rect;
+            // eslint-disable-next-line no-await-in-loop -- see above
+            await nextFrameOrAfter(signal, settleFrameMs);
+            continue;
+          }
+
+          previous = undefined;
+          stableFrames = 0;
+          settleFrames = 0;
+          if (platform.isAwaitingLayout(target)) {
+            // eslint-disable-next-line no-await-in-loop -- see above
+            await nextFrame(signal);
+          } else if (!hasChanged) {
+            // Not there yet: sleep until something changes instead of polling.
+            // eslint-disable-next-line no-await-in-loop -- see above
+            await sleepUntilChange();
+            wake = undefined;
+          }
+        }
+
+        return undefined;
+      } finally {
+        signal.removeEventListener('abort', onAbort);
+        unsubscribe();
+      }
+    },
+
+    getViewport: platform.getViewport,
+
+    measuresWhileScrolling: platform.measuresWhileScrolling,
+
+    async reveal(target, request): Promise<void> {
+      const containers = await platform.scrollContainers(target);
+      if (request.signal.aborted) {
+        return;
+      }
+
+      await revealInScrollContainers({
+        containers,
+        async measureTarget() {
+          const measurement = await platform.measure(target);
+          return measurement?.rect;
+        },
+        margins: request.margins,
+        animated: request.behavior === 'smooth' && !platform.reducedMotion.get(),
+        signal: request.signal,
+        onScrollStart: request.onScrollStart,
+      });
+    },
+
+    observe(target: TourTarget | undefined, onChange, signal): void {
+      if (signal.aborted) {
+        return;
+      }
+
+      // At most one call per frame, however many events arrive.
+      let cancelFrame: (() => void) | undefined;
+      const schedule = (): void => {
+        if (cancelFrame !== undefined || signal.aborted) {
+          return;
+        }
+
+        cancelFrame = requestFrame(() => {
+          cancelFrame = undefined;
+          if (!signal.aborted) {
+            onChange();
+          }
+        });
+      };
+
+      const unsubscribe = platform.subscribe(target, schedule);
+      signal.addEventListener('abort', () => {
+        cancelFrame?.();
+        unsubscribe();
+      });
+    },
+
+    getPixelRatio: platform.getPixelRatio,
+
+    nextFrame,
+  };
+}

package/src/shared/platform/platform.type.ts

@@ -0,0 +1,81 @@
+import type {TargetMeasurement} from '../engine/tour-adapter.type.js';
+import type {Box, Point, Viewport} from '../geometry/geometry.type.js';
+import type {TourTarget} from '../types/tour-step.type.js';
+
+/**
+ * What the tour needs from a platform (web, React Native): raw facts about the screen and the
+ * app's views, and nothing else. Everything built on them — waiting for targets, following them,
+ * scrolling them into view, deciding when scrolling has finished — is shared (see
+ * `createTourAdapter`), so it behaves the same everywhere.
+ *
+ * Every member is required: a platform that lacks one does not compile.
+ */
+export type PlatformAdapter = {
+  /** Where the target is, in the tour layer's coordinates, or `undefined` when it is not rendered. */
+  readonly measure: (target: TourTarget) => Promise<TargetMeasurement | undefined>;
+  /**
+   * Calls `onChange` whenever the target, the layout around it or the viewport may have changed.
+   * Event-driven: no calls while nothing changes. Calling too often is fine (calls are coalesced
+   * per frame and results compared). Returns the unsubscribe function.
+   */
+  readonly subscribe: (target: TourTarget | undefined, onChange: () => void) => () => void;
+  /**
+   * True when the target exists but cannot be measured yet, and no event will announce when it
+   * can (React Native: registered, but not laid out yet). The tour then checks every frame.
+   */
+  readonly isAwaitingLayout: (target: TourTarget) => boolean;
+  /** The scroll containers around the target, innermost first, including the page where it scrolls. */
+  readonly scrollContainers: (target: TourTarget) => Promise<readonly ScrollContainer[]>;
+  /**
+   * The visible area of the tour layer and what covers its edges (safe areas, the on-screen
+   * keyboard). Pass the step's target so that a bar containing it does not count as covering it.
+   */
+  readonly getViewport: (target?: TourTarget) => Viewport;
+  /** Whether the user asked the system to reduce motion. */
+  readonly reducedMotion: ExternalValue<boolean>;
+  /**
+   * Whether `measure` sees targets move while a scroll animation runs. When it does not (React
+   * Native: on the New Architecture, measurements only catch up once a scroll has finished), the
+   * highlight moves straight to where the target will end up instead of following it.
+   */
+  readonly measuresWhileScrolling: boolean;
+  /** Device pixel ratio, used to place the tooltip on whole device pixels. */
+  readonly getPixelRatio: () => number;
+};
+
+/** A value that can change outside React (a system setting), readable with `useSyncExternalStore`. */
+export type ExternalValue<T> = {
+  readonly get: () => T;
+  readonly subscribe: (listener: () => void) => () => void;
+};
+
+/** One scrollable area between the target and the screen (a nested scroller, a list, or the page itself). */
+export type ScrollContainer = {
+  /** Current geometry, or `undefined` when the container is not rendered. */
+  readonly measure: () => Promise<ScrollContainerMetrics | undefined>;
+  /**
+   * Scrolls to `offset` and resolves once this container has finished scrolling (or cannot get
+   * further). Stops waiting as soon as `signal` is aborted.
+   */
+  readonly scrollTo: (offset: Point, options: ScrollOptions) => Promise<void>;
+};
+
+export type ScrollOptions = {
+  readonly animated: boolean;
+  readonly signal: AbortSignal;
+};
+
+export type ScrollContainerMetrics = {
+  /** The part of the container's viewport content should be revealed in (scroll-padding already applied), in layer coordinates. */
+  readonly area: Box;
+  readonly offset: Point;
+  /**
+   * The range the tour may scroll in, per axis. Usually `0` to the end of the content; on an axis
+   * the tour must not scroll (the app's own `overflow: hidden`), both are the current offset. Offsets
+   * can be negative at rest (content insets, centred content).
+   */
+  readonly minOffset: Point;
+  readonly maxOffset: Point;
+  /** Elements over this area that do not scroll with its content (sticky headers, floating buttons), in layer coordinates. */
+  readonly obstacles?: readonly Box[];
+};

package/src/shared/platform/reveal-in-scroll-containers.ts

@@ -0,0 +1,78 @@
+import {withTimeout} from '../engine/abort.util.js';
+import {clamp} from '../geometry/box.util.js';
+import type {Box, Insets, Point} from '../geometry/geometry.type.js';
+import {computeRevealDelta} from '../geometry/reveal.util.js';
+import type {ScrollContainer} from './platform.type.js';
+
+export type RevealOptions = {
+  /** Innermost container first. */
+  readonly containers: readonly ScrollContainer[];
+  readonly measureTarget: () => Promise<Box | undefined>;
+  /** Space to keep around the target, most generous first (see `buildRevealMargins`). */
+  readonly margins: readonly Insets[];
+  readonly animated: boolean;
+  readonly signal: AbortSignal;
+  /**
+   * Called once, right before the first container scrolls, with where the target will be once
+   * everything has scrolled. Not called if nothing needs to scroll.
+   */
+  readonly onScrollStart?: (destination: Box) => void;
+};
+
+const minimumScroll = 0.5;
+/** Safety cap: a scroll that never reports finishing (interrupted, snapped elsewhere) does not hold the tour up longer. */
+export const settleTimeoutMs = 1500;
+
+/**
+ * Scrolls every container around the target just enough to bring it (plus margin) into view, all
+ * at once: each container's scroll is computed innermost first, on the position the target will
+ * have after the inner containers have scrolled (an inner scroll moves the target by exactly the
+ * scrolled distance), and then all containers scroll together as one movement. Resolves once every
+ * container has finished scrolling.
+ */
+export async function revealInScrollContainers(options: RevealOptions): Promise<boolean> {
+  const metrics = await Promise.all(options.containers.map(async (container) => container.measure()));
+  let predicted = await options.measureTarget();
+  if (options.signal.aborted || !predicted) {
+    return false;
+  }
+
+  const moves: Array<{readonly container: ScrollContainer; readonly offset: Point}> = [];
+  for (const [index, container] of options.containers.entries()) {
+    const current = metrics[index];
+    if (!current) {
+      continue;
+    }
+
+    const delta = computeRevealDelta(predicted, current.area, options.margins, current.obstacles);
+    const offset: Point = {
+      x: clamp(current.offset.x + delta.x, current.minOffset.x, Math.max(current.minOffset.x, current.maxOffset.x)),
+      y: clamp(current.offset.y + delta.y, current.minOffset.y, Math.max(current.minOffset.y, current.maxOffset.y)),
+    };
+    const applied: Point = {x: offset.x - current.offset.x, y: offset.y - current.offset.y};
+    if (Math.abs(applied.x) < minimumScroll && Math.abs(applied.y) < minimumScroll) {
+      continue;
+    }
+
+    moves.push({container, offset});
+    // Scrolling by `applied` moves the content (and the target) the other way.
+    predicted = {...predicted, x: predicted.x - applied.x, y: predicted.y - applied.y};
+  }
+
+  if (moves.length === 0) {
+    return false;
+  }
+
+  options.onScrollStart?.(predicted);
+  await withTimeout(
+    async (signal) => {
+      await Promise.all(
+        moves.map(async (move) => move.container.scrollTo(move.offset, {animated: options.animated, signal})),
+      );
+      return true;
+    },
+    options.signal,
+    settleTimeoutMs,
+  );
+  return true;
+}

package/src/shared/react/tour-context.ts

@@ -0,0 +1,28 @@
+import {createContext} from 'react';
+import {devWarn} from '../engine/report.util.js';
+import type {TourEngine} from '../engine/tour-engine.js';
+import type {TourContextType} from '../types/tour-context.type.js';
+
+function outsideProvider(): void {
+  devWarn('useTour() was called outside of <TourProvider>; the call has no effect.');
+}
+
+const defaultTourContext: TourContextType = {
+  isActive: false,
+  currentStep: 0,
+  steps: [],
+  currentTourId: undefined,
+  startTour: outsideProvider,
+  endTour: outsideProvider,
+  nextStep: outsideProvider,
+  prevStep: outsideProvider,
+  goToStep: outsideProvider,
+};
+
+/** Public tour state and actions (what `useTour()` returns). */
+export const TourContext = createContext(defaultTourContext);
+TourContext.displayName = 'TourContext';
+
+/** The engine, for the built-in renderer and platform hooks. Not part of the public API. */
+export const TourEngineContext = createContext<TourEngine | undefined>(undefined);
+TourEngineContext.displayName = 'TourEngineContext';

package/src/shared/react/tour-provider-core.ts

@@ -0,0 +1,67 @@
+import {type ComponentType, type ReactNode, useMemo, useState, useSyncExternalStore} from 'react';
+import type {TourEngine} from '../engine/tour-engine.js';
+import {createTourAdapter} from '../platform/create-tour-adapter.js';
+import type {PlatformAdapter} from '../platform/platform.type.js';
+import {DefaultTooltip} from '../renderer/default-tooltip.js';
+import type {TourRenderer} from '../renderer/renderer.type.js';
+import type {TourOverlayProps} from '../renderer/tour-overlay.js';
+import type {TourEndCallback} from '../types/tour-end-info.type.js';
+import type {TourI18n} from '../types/tour-i18n.type.js';
+import type {TourTheme} from '../types/tour-theme.type.js';
+import type {TourTooltipProps} from '../types/tour-tooltip-props.type.js';
+import {resolveI18n} from '../utils/i18n.util.js';
+import {resolveTheme} from '../utils/theme.util.js';
+import {useTourEngine} from './tour-root.js';
+
+/** Props of `TourProvider` on every platform. Platforms may add their own (React Native: `insets`). */
+export type TourProviderBaseProps = {
+  readonly children?: ReactNode;
+  /** Colours of the built-in tooltip and overlay. */
+  readonly theme?: TourTheme;
+  /** Texts of the built-in tooltip. */
+  readonly i18n?: TourI18n;
+  /** Called once whenever a tour ends, after the tour's own `onTourEnd`. */
+  readonly onTourEnd?: TourEndCallback;
+  /**
+   * Whether clicking or tapping the dimmed area ends the tour (with the reason `'blur'`).
+   * @defaultValue `true`
+   */
+  readonly closeOnOverlayClick?: boolean;
+  /**
+   * Replaces the content of the tooltip card. The tour still measures, positions, animates and
+   * focuses it, and keeps it on screen.
+   */
+  readonly TooltipComponent?: ComponentType<TourTooltipProps>;
+};
+
+export type TourCore = {
+  readonly engine: TourEngine;
+  /** Everything the overlay needs; the platform renders `<TourOverlay {...overlay} />` where the tour is drawn. */
+  readonly overlay: TourOverlayProps;
+};
+
+const neverReduced = (): boolean => false;
+
+/**
+ * What every `TourProvider` does, whatever the platform: creates the engine on top of the
+ * platform's facts, resolves theme and texts, and prepares the overlay. `platform` and `renderer`
+ * must keep their identity for the lifetime of the provider.
+ */
+export function useTourCore(props: TourProviderBaseProps, platform: PlatformAdapter, renderer: TourRenderer): TourCore {
+  const [adapter] = useState(() => createTourAdapter(platform));
+  const engine = useTourEngine(adapter, props.onTourEnd);
+  const isReducedMotion = useSyncExternalStore(
+    platform.reducedMotion.subscribe,
+    platform.reducedMotion.get,
+    neverReduced,
+  );
+  const theme = useMemo(() => resolveTheme(props.theme), [props.theme]);
+  const i18n = useMemo(() => resolveI18n(props.i18n), [props.i18n]);
+  const Tooltip = props.TooltipComponent ?? DefaultTooltip;
+  const isOverlayDismissible = props.closeOnOverlayClick ?? true;
+  const overlay = useMemo<TourOverlayProps>(
+    () => ({engine, renderer, theme, i18n, Tooltip, isOverlayDismissible, isReducedMotion}),
+    [engine, renderer, theme, i18n, Tooltip, isOverlayDismissible, isReducedMotion],
+  );
+  return {engine, overlay};
+}

package/src/shared/react/tour-root.tsx

@@ -0,0 +1,34 @@
+import {type ReactNode, useEffect, useMemo, useState, useSyncExternalStore} from 'react';
+import type {TourAdapter} from '../engine/tour-adapter.type.js';
+import {createTourEngine, type TourEngine} from '../engine/tour-engine.js';
+import type {TourContextType} from '../types/tour-context.type.js';
+import type {TourEndCallback} from '../types/tour-end-info.type.js';
+import {TourContext, TourEngineContext} from './tour-context.js';
+import {useIsomorphicLayoutEffect} from './use-isomorphic-layout-effect.hook.js';
+
+/** Creates the engine once and keeps its options in sync with the latest props. */
+export function useTourEngine(adapter: TourAdapter, onTourEnd: TourEndCallback | undefined): TourEngine {
+  const [engine] = useState(() => createTourEngine({adapter, onTourEnd}));
+  // Latest props: callback identity never matters, so inline callbacks cannot restart anything.
+  useIsomorphicLayoutEffect(() => {
+    engine.configure({adapter, onTourEnd});
+  });
+  useEffect(() => engine.mount(), [engine]);
+  return engine;
+}
+
+type TourRootProps = {
+  readonly engine: TourEngine;
+  readonly children: ReactNode;
+};
+
+/** Provides the public tour context (for `useTour`) and the engine (for the renderer). */
+export function TourRoot({engine, children}: TourRootProps): ReactNode {
+  const state = useSyncExternalStore(engine.subscribe, engine.getPublicState, engine.getPublicState);
+  const value = useMemo<TourContextType>(() => ({...state, ...engine.actions}), [state, engine]);
+  return (
+    <TourEngineContext.Provider value={engine}>
+      <TourContext.Provider value={value}>{children}</TourContext.Provider>
+    </TourEngineContext.Provider>
+  );
+}

package/src/shared/react/use-isomorphic-layout-effect.hook.ts

@@ -0,0 +1,7 @@
+import {useEffect, useLayoutEffect} from 'react';
+
+const canUseLayoutEffect =
+  typeof document !== 'undefined' || (typeof navigator !== 'undefined' && navigator.product === 'ReactNative');
+
+/** `useLayoutEffect` in the browser and on React Native; `useEffect` during server rendering (avoids React 18's SSR warning). */
+export const useIsomorphicLayoutEffect = canUseLayoutEffect ? useLayoutEffect : useEffect;

package/src/shared/react/use-tour-view.hook.ts

@@ -0,0 +1,17 @@
+import {useContext, useSyncExternalStore} from 'react';
+import type {TourEngine, TourViewState} from '../engine/tour-engine.js';
+import {TourEngineContext} from './tour-context.js';
+
+export function useTourEngineContext(): TourEngine {
+  const engine = useContext(TourEngineContext);
+  if (!engine) {
+    throw new Error('[react-tour-kit] This component must be rendered inside <TourProvider>.');
+  }
+
+  return engine;
+}
+
+/** What the renderer draws. Re-renders only on structural changes (step, phase, layout). */
+export function useTourView(engine: TourEngine): TourViewState {
+  return useSyncExternalStore(engine.subscribe, engine.getViewState, engine.getViewState);
+}

package/src/shared/react/use-tour.hook.ts

@@ -0,0 +1,11 @@
+import {useContext} from 'react';
+import type {TourContextType} from '../types/tour-context.type.js';
+import {TourContext} from './tour-context.js';
+
+/**
+ * The current tour's state and the functions to control it. The functions keep their identity for
+ * the lifetime of the `TourProvider`, so they are safe to use in effect dependencies.
+ */
+export function useTour(): TourContextType {
+  return useContext(TourContext);
+}

package/src/shared/renderer/default-tooltip.tsx

@@ -0,0 +1,52 @@
+import type {ReactNode} from 'react';
+import type {TourTooltipProps} from '../types/tour-tooltip-props.type.js';
+import {useRendererContext} from './renderer-context.js';
+import {tooltipModel} from './tooltip-model.js';
+
+/** The built-in tooltip: the same structure and texts on every platform, drawn with the platform's card parts. */
+export function DefaultTooltip(props: TourTooltipProps): ReactNode {
+  const {renderer, i18n} = useRendererContext();
+  const {Card, Arrow, Header, Counter, CloseButton, Body, Title, Content, Footer, Button, Dots, Dot, Ellipsis} =
+    renderer.card;
+  const model = tooltipModel(props, i18n);
+  return (
+    <Card placement={props.placement}>
+      {model.arrow ? <Arrow side={model.arrow.side} offset={model.arrow.offset} /> : null}
+      <Header>
+        <Counter text={model.counter} />
+        <CloseButton label={model.closeLabel} onPress={props.onClose} />
+      </Header>
+      <Body>
+        <Title id={props.titleId}>{props.step.title}</Title>
+        <Content id={props.descriptionId}>{props.step.content}</Content>
+      </Body>
+      <Footer>
+        <Button
+          kind="previous"
+          label={model.previous.label}
+          isDisabled={model.previous.isDisabled}
+          onPress={props.onPrev}
+        />
+        {model.dots ? (
+          <Dots label={model.counter}>
+            {model.dots.map((dot) =>
+              dot.kind === 'ellipsis' ? (
+                <Ellipsis key={dot.key} />
+              ) : (
+                <Dot
+                  key={dot.index}
+                  label={dot.label}
+                  isCurrent={dot.isCurrent}
+                  onPress={() => {
+                    props.onGoToStep(dot.index);
+                  }}
+                />
+              ),
+            )}
+          </Dots>
+        ) : null}
+        <Button kind="next" label={model.next.label} isDisabled={false} onPress={props.onNext} />
+      </Footer>
+    </Card>
+  );
+}

package/src/shared/renderer/motion.ts

@@ -0,0 +1,59 @@
+import type {TourPlacement} from '../types/tour-step.type.js';
+import type {Entrance} from './renderer.type.js';
+
+/** Timing of every animation, the same on every platform. */
+export const motion = {
+  fadeInMs: 200,
+  fadeOutMs: 150,
+  /** With reduced motion turned on: short fades, no movement. */
+  reducedMs: 100,
+  /** The spotlight moving from one target to the next. */
+  morphMs: 250,
+  /** The spotlight following a target that is being scrolled into view, frame by frame. */
+  chaseMs: 120,
+  enterMs: 200,
+  /** The tooltip starts entering while the spotlight is still on its way. */
+  enterDelayMs: 100,
+  /** 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,
+  /** Control points of the standard easing curve (`cubic-bezier`). */
+  easing: [0.2, 0, 0, 1],
+} as const;
+
+export function fadeDuration(isClosing: boolean, isReducedMotion: boolean): number {
+  if (isReducedMotion) {
+    return motion.reducedMs;
+  }
+
+  return isClosing ? motion.fadeOutMs : motion.fadeInMs;
+}
+
+const entranceDirection: Record<TourPlacement | 'center', readonly [number, number]> = {
+  // Above the target: comes down towards it; below: comes up; and so on.
+  top: [0, 1],
+  bottom: [0, -1],
+  left: [1, 0],
+  right: [-1, 0],
+  center: [0, 0],
+};
+
+export function entranceFor(
+  placement: TourPlacement | 'center',
+  {isDelayed, isReducedMotion}: {readonly isDelayed: boolean; readonly isReducedMotion: boolean},
+): Entrance {
+  if (isReducedMotion) {
+    return {dx: 0, dy: 0, scale: 1, durationMs: motion.reducedMs, delayMs: 0};
+  }
+
+  const [x, y] = entranceDirection[placement];
+  return {
+    dx: x * motion.enterOffset,
+    dy: y * motion.enterOffset,
+    scale: motion.enterScale,
+    durationMs: motion.enterMs,
+    delayMs: isDelayed ? motion.enterDelayMs : 0,
+  };
+}

package/src/shared/renderer/renderer-context.ts

@@ -0,0 +1,33 @@
+import {createContext, useContext} from 'react';
+import type {ResolvedI18n} from '../utils/i18n.util.js';
+import type {ResolvedTheme} from '../utils/theme.util.js';
+import type {TourRenderer} from './renderer.type.js';
+
+export type RendererContextValue = {
+  readonly renderer: TourRenderer;
+  readonly theme: ResolvedTheme;
+  readonly i18n: ResolvedI18n;
+};
+
+/** The platform's primitives, the theme and the texts, for everything drawn inside the tour. Internal. */
+export const RendererContext = createContext<RendererContextValue | undefined>(undefined);
+RendererContext.displayName = 'TourRendererContext';
+
+export function useRendererContext(): RendererContextValue {
+  const value = useContext(RendererContext);
+  if (!value) {
+    throw new Error('[react-tour-kit] The built-in tooltip can only be rendered by the tour.');
+  }
+
+  return value;
+}
+
+export type TooltipLimits = {
+  readonly maxWidth: number;
+  readonly maxHeight: number;
+};
+
+/** Size limits of the tooltip being rendered; platforms that cannot express them in styles size the card with them. */
+const defaultLimits: TooltipLimits = {maxWidth: 380, maxHeight: 600};
+export const TooltipLimitsContext = createContext(defaultLimits);
+TooltipLimitsContext.displayName = 'TourTooltipLimitsContext';