@robertlinde/react-tour-kit 0.8.8 → 1.0.0

package/src/shared/engine/abort.util.ts

@@ -0,0 +1,84 @@
+import {requestFrame} from '../utils/frame.util.js';
+
+/**
+ * Runs `run` with a child signal that is aborted when `parent` aborts or after `timeoutMs`.
+ * Resolves `undefined` on timeout, abort, or when `run` rejects (callers check `parent.aborted`
+ * to tell an abort apart from a timeout).
+ *
+ * Only `aborted` and the `abort` event are used, because the AbortController shipped with
+ * React Native supports nothing else (no `reason`, no `throwIfAborted`, no `AbortSignal.any`).
+ */
+export async function withTimeout<T>(
+  run: (signal: AbortSignal) => Promise<T | undefined>,
+  parent: AbortSignal,
+  timeoutMs: number,
+): Promise<T | undefined> {
+  if (parent.aborted) {
+    return undefined;
+  }
+
+  const child = new AbortController();
+  const abortChild = (): void => {
+    child.abort();
+  };
+
+  parent.addEventListener('abort', abortChild);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stopped = new Promise<undefined>((resolve) => {
+    child.signal.addEventListener('abort', () => {
+      resolve(undefined);
+    });
+    timer = setTimeout(abortChild, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([run(child.signal).catch((): undefined => undefined), stopped]);
+  } finally {
+    clearTimeout(timer);
+    parent.removeEventListener('abort', abortChild);
+    child.abort();
+  }
+}
+
+/**
+ * Resolves on the next frame, after `ms` at the latest (browsers stop frames in background tabs,
+ * but not timers), or right away when `signal` is aborted.
+ */
+export async function nextFrameOrAfter(signal: AbortSignal, ms: number): Promise<void> {
+  if (signal.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    const done = (): void => {
+      cancelFrame();
+      clearTimeout(timer);
+      signal.removeEventListener('abort', done);
+      resolve();
+    };
+
+    const cancelFrame = requestFrame(done);
+    const timer = setTimeout(done, ms);
+    signal.addEventListener('abort', done);
+  });
+}
+
+/** Resolves on the next frame, or immediately when `signal` is aborted. */
+export async function nextFrame(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    const onAbort = (): void => {
+      cancelFrame();
+      resolve();
+    };
+
+    const cancelFrame = requestFrame(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    });
+    signal.addEventListener('abort', onAbort);
+  });
+}

package/src/shared/engine/report.util.ts

@@ -0,0 +1,58 @@
+declare const process: {readonly env: {readonly NODE_ENV?: string}};
+
+function computeIsDevelopment(): boolean {
+  try {
+    // Bundlers (Vite, webpack, Metro, Next.js) replace this expression statically.
+    return process.env.NODE_ENV !== 'production';
+  } catch {
+    // Unbundled browser ESM: no `process`, treat as production.
+    return false;
+  }
+}
+
+export const isDevelopment = computeIsDevelopment();
+
+/** Prints a development-only warning, prefixed so it is easy to find. */
+export function devWarn(message: string): void {
+  if (isDevelopment) {
+    // eslint-disable-next-line no-console -- intentional development warning
+    console.warn(`[react-tour-kit] ${message}`);
+  }
+}
+
+/**
+ * Reports an error thrown by user code without interrupting the tour. Uses `reportError` where it
+ * exists (browsers; error trackers pick it up), otherwise `console.error` (React Native shows a
+ * red box in development and does not crash in production).
+ */
+export function reportError(error: unknown): void {
+  const report = (globalThis as {reportError?: (error: unknown) => void}).reportError;
+  if (typeof report === 'function') {
+    report(error);
+    return;
+  }
+
+  // eslint-disable-next-line no-console -- fallback error reporting
+  console.error(error);
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === 'object' || typeof value === 'function') &&
+    value !== null &&
+    'then' in value &&
+    typeof value.then === 'function'
+  );
+}
+
+/** Calls a user callback; errors (sync or async) are reported and never propagate. */
+export function safeInvoke(callback: () => unknown): void {
+  try {
+    const result = callback();
+    if (isPromiseLike(result)) {
+      result.then(undefined, reportError);
+    }
+  } catch (error) {
+    reportError(error);
+  }
+}

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

@@ -0,0 +1,62 @@
+import type {Box, Insets, Viewport} from '../geometry/geometry.type.js';
+import type {TourTarget} from '../types/tour-step.type.js';
+
+/** Where a target is, in the tour layer's coordinate space. */
+export type TargetMeasurement = {
+  readonly rect: Box;
+  /**
+   * The area the target can be seen through: the intersection of the scroll containers and
+   * clipping ancestors around it. `undefined` when nothing clips it.
+   */
+  readonly clip: Box | undefined;
+  /** Elements that stay put while the content scrolls (sticky headers, floating buttons) and overlap the target. */
+  readonly occluders?: readonly Box[];
+};
+
+export type RevealRequest = {
+  /** Space to keep around the target, most generous first. */
+  readonly margins: readonly Insets[];
+  /** `'smooth'` is downgraded to `'instant'` by the adapter when the user prefers reduced motion. */
+  readonly behavior: 'smooth' | 'instant';
+  readonly signal: AbortSignal;
+  /**
+   * Must be called right before the first scroll starts, and not at all if nothing scrolls, with
+   * where the target will be once scrolling has finished.
+   */
+  readonly onScrollStart: (destination: Box) => void;
+};
+
+/**
+ * Everything platform-specific the engine needs. Adapters never own timeouts; they only have to
+ * stop work promptly when a signal is aborted.
+ */
+export type TourAdapter = {
+  /** Measures a target, or resolves `undefined` when it is not rendered. */
+  readonly measure: (target: TourTarget) => Promise<TargetMeasurement | undefined>;
+  /** Resolves as soon as the target is rendered and measurable. Event-driven where the platform allows; never busy-polls. */
+  readonly waitForTarget: (target: TourTarget, signal: AbortSignal) => Promise<TargetMeasurement | undefined>;
+  /**
+   * The visible area of the tour layer and what covers its edges (safe areas, the on-screen
+   * keyboard, stuck navigation bars). Pass the step's target so that a bar containing it does not
+   * count as covering it.
+   */
+  readonly getViewport: (target?: TourTarget) => Viewport;
+  /**
+   * 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;
+  /** Scrolls every container around the target just enough to show it with the given margin, and resolves once scrolling has settled. */
+  readonly reveal: (target: TourTarget, request: RevealRequest) => Promise<void>;
+  /**
+   * Calls `onChange` (at most once per frame) whenever the target's position or size, or the
+   * viewport, may have changed. Over-notifying is fine; the engine compares values. Stops when
+   * `signal` is aborted. `target` is `undefined` for centred steps (viewport changes only).
+   */
+  readonly observe: (target: TourTarget | undefined, onChange: () => void, signal: AbortSignal) => void;
+  /** Device pixel ratio, used to place the tooltip on whole device pixels. */
+  readonly getPixelRatio?: () => number;
+  /** Resolves on the next frame (or right away when `signal` is aborted). */
+  readonly nextFrame: (signal: AbortSignal) => Promise<void>;
+};