@robertlinde/react-tour-kit 0.8.9 → 1.0.0

package/src/react-native-platform/reduced-motion.ts

@@ -0,0 +1,47 @@
+import {AccessibilityInfo} from 'react-native';
+import type {ExternalValue} from '../shared/platform/platform.type.js';
+
+/** The system's "reduce motion" setting, live. Listens to the system only while someone is subscribed. */
+export function createReducedMotionSetting(): ExternalValue<boolean> {
+  let value = false;
+  const listeners = new Set<() => void>();
+  let stop: (() => void) | undefined;
+  const set = (next: boolean): void => {
+    if (next !== value) {
+      value = next;
+      // Snapshot: listeners may unsubscribe while being notified.
+      const snapshot = [...listeners];
+      for (const listener of snapshot) {
+        listener();
+      }
+    }
+  };
+
+  return {
+    get: () => value,
+    subscribe(listener) {
+      listeners.add(listener);
+      if (!stop) {
+        let isListening = true;
+        void AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+          if (isListening) {
+            set(enabled);
+          }
+        });
+        const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', set);
+        stop = (): void => {
+          isListening = false;
+          subscription.remove();
+        };
+      }
+
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stop?.();
+          stop = undefined;
+        }
+      };
+    },
+  };
+}

package/src/react-native-platform/registry.ts

@@ -0,0 +1,70 @@
+import type {RefObject} from 'react';
+
+/**
+ * Targets and scroll views registered by `useTourTarget` / `useTourScrollView`, one registry per
+ * `TourProvider`. A target id can be registered by several components at once (two screens of a
+ * stack during a transition, tabs that stay mounted); unregistering only removes the caller's own
+ * registration, and the newest registration comes first.
+ */
+export type TourRegistry = {
+  readonly registerTarget: (id: string, ref: RefObject<unknown>) => () => void;
+  /** Refs registered for `id`, newest first. */
+  readonly targets: (id: string) => ReadonlyArray<RefObject<unknown>>;
+  readonly registerScrollView: (ref: RefObject<unknown>) => () => void;
+  readonly scrollViews: () => ReadonlyArray<RefObject<unknown>>;
+  /** Called after any registration change. */
+  readonly subscribe: (listener: () => void) => () => void;
+};
+
+export function createRegistry(): TourRegistry {
+  const targets = new Map<string, Array<RefObject<unknown>>>();
+  const scrollViews = new Set<RefObject<unknown>>();
+  const listeners = new Set<() => void>();
+  const notify = (): void => {
+    // Snapshot: listeners may unsubscribe while being notified.
+    const snapshot = [...listeners];
+    for (const listener of snapshot) {
+      listener();
+    }
+  };
+
+  return {
+    registerTarget(id, ref) {
+      const entries = targets.get(id) ?? [];
+      entries.push(ref);
+      targets.set(id, entries);
+      notify();
+      return () => {
+        const current = targets.get(id);
+        const index = current?.lastIndexOf(ref) ?? -1;
+        if (current && index !== -1) {
+          current.splice(index, 1);
+          if (current.length === 0) {
+            targets.delete(id);
+          }
+
+          notify();
+        }
+      };
+    },
+    // Newest first. (Not `toReversed`: ES2023 is not available on every supported React Native version.)
+    // eslint-disable-next-line unicorn/no-array-reverse
+    targets: (id) => [...(targets.get(id) ?? [])].reverse(),
+    registerScrollView(ref) {
+      scrollViews.add(ref);
+      notify();
+      return () => {
+        if (scrollViews.delete(ref)) {
+          notify();
+        }
+      };
+    },
+    scrollViews: () => [...scrollViews],
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/react-native-platform/tour-provider.tsx

@@ -0,0 +1,148 @@
+import {type ReactNode, useEffect, useMemo, useState, useSyncExternalStore} from 'react';
+import {Keyboard, PixelRatio, Platform, StyleSheet, View} from 'react-native';
+import {useIsomorphicLayoutEffect} from '../shared/react/use-isomorphic-layout-effect.hook.js';
+import {TourRoot} from '../shared/react/tour-root.js';
+import {type TourProviderBaseProps, useTourCore} from '../shared/react/tour-provider-core.js';
+import {createHostStore} from './host-store.js';
+import type {TourInsets} from './insets.util.js';
+import {nativeRenderer} from './layer/native-renderer.js';
+import {HostView} from './layer/tour-host.js';
+import {NativeTourContext, type NativeTourContextValue} from './native-context.js';
+import {createNativeEnvironment} from './native-environment.js';
+import {createNativePlatform} from './native-platform.js';
+import {createReducedMotionSetting} from './reduced-motion.js';
+import {createRegistry} from './registry.js';
+
+export type TourProviderProps = TourProviderBaseProps & {
+  /**
+   * Safe-area insets, for example `useSafeAreaInsets()` from react-native-safe-area-context.
+   * Without them, conservative defaults keep the tooltip clear of notches and system bars.
+   */
+  readonly insets?: TourInsets;
+};
+
+/**
+ * Provides `useTour()` and renders the tour above your app. Place it at the root, around your
+ * navigation container and outside any `SafeAreaView`; pass safe-area `insets` instead.
+ */
+export function TourProvider({insets, ...props}: TourProviderProps): ReactNode {
+  const [registry] = useState(createRegistry);
+  const [hosts] = useState(createHostStore);
+  const [environment] = useState(createNativeEnvironment);
+  const [platform] = useState(() =>
+    createNativePlatform({
+      registry,
+      getHost: hosts.activeHost,
+      getInsets: () => environment.getInsets(hosts.activeHost()?.size ?? {width: 0, height: 0}),
+      subscribeLayout: hosts.subscribeLayout,
+      reducedMotion: createReducedMotionSetting(),
+      getPixelRatio: () => PixelRatio.get(),
+    }),
+  );
+  const {engine, overlay} = useTourCore(props, platform, nativeRenderer);
+  const {isActive} = useSyncExternalStore(engine.subscribe, engine.getPublicState, engine.getPublicState);
+  const isRootActive = useSyncExternalStore(hosts.subscribe, hosts.isRootActive, hosts.isRootActive);
+
+  // New insets (rotation, split screen) move the safe area.
+  useIsomorphicLayoutEffect(() => {
+    environment.setInsets(insets);
+    hosts.notifyLayout();
+  }, [environment, hosts, insets?.top, insets?.right, insets?.bottom, insets?.left]);
+
+  // The keyboard shrinks the area the tooltip may use.
+  useEffect(() => {
+    const show = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
+    const hide = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide';
+    let keyboard: {readonly top: number; readonly height: number} | undefined;
+    const apply = (overlap: number): void => {
+      if (environment.setKeyboardOverlap(overlap)) {
+        hosts.notifyLayout();
+      }
+    };
+
+    const update = (): void => {
+      const current = keyboard;
+      if (!current) {
+        apply(0);
+        return;
+      }
+
+      // Android apps that resize with the keyboard (`adjustResize` without edge-to-edge) have
+      // already made room for it: only the part still covering the layer counts.
+      const host = hosts.activeHost()?.instance;
+      if (Platform.OS !== 'android' || !canMeasureInWindow(host)) {
+        apply(current.height);
+        return;
+      }
+
+      host.measureInWindow((_x, y, _width, height) => {
+        if (keyboard === current) {
+          apply(y + height - current.top);
+        }
+      });
+    };
+
+    const subscriptions = [
+      Keyboard.addListener(show, (event) => {
+        keyboard = {top: event.endCoordinates.screenY, height: event.endCoordinates.height};
+        update();
+      }),
+      Keyboard.addListener(hide, () => {
+        keyboard = undefined;
+        update();
+      }),
+    ];
+    // The layer resizing for the keyboard changes how much of it the keyboard covers.
+    const unsubscribeLayout = hosts.subscribeLayout(() => {
+      if (keyboard) {
+        update();
+      }
+    });
+    return (): void => {
+      unsubscribeLayout();
+      for (const subscription of subscriptions) {
+        subscription.remove();
+      }
+    };
+  }, [environment, hosts]);
+
+  const context = useMemo<NativeTourContextValue>(() => ({registry, hosts, overlay}), [registry, hosts, overlay]);
+  const hidesApp = isActive && isRootActive;
+
+  return (
+    <TourRoot engine={engine}>
+      <NativeTourContext.Provider value={context}>
+        <View collapsable={false} style={styles.root}>
+          {/* Hidden from screen readers while the tour (a modal) is open over it. Not while a
+              TourHost draws the tour: that host can be inside this view (modal screens on Android). */}
+          <View
+            collapsable={false}
+            style={styles.root}
+            importantForAccessibility={hidesApp ? 'no-hide-descendants' : 'auto'}
+            accessibilityElementsHidden={hidesApp}
+          >
+            {props.children}
+          </View>
+          <HostView isRoot />
+        </View>
+      </NativeTourContext.Provider>
+    </TourRoot>
+  );
+}
+
+type WindowMeasurable = {
+  readonly measureInWindow: (callback: (x: number, y: number, width: number, height: number) => void) => void;
+};
+
+function canMeasureInWindow(value: unknown): value is WindowMeasurable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'measureInWindow' in value &&
+    typeof value.measureInWindow === 'function'
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {flex: 1},
+});

package/src/react-native.ts

@@ -0,0 +1,15 @@
+// React Native entry point: import from '@robertlinde/react-tour-kit/react-native'.
+
+export {TourProvider, type TourProviderProps} from './react-native-platform/tour-provider.js';
+export {TourHost} from './react-native-platform/layer/tour-host.js';
+export {useTourTarget} from './react-native-platform/hooks/use-tour-target.hook.js';
+export {useTourScrollView} from './react-native-platform/hooks/use-tour-scroll-view.hook.js';
+export {useTour} from './shared/react/use-tour.hook.js';
+export {getTruncatedDots, type DotItem} from './shared/utils/get-truncated-dots.util.js';
+export type {TourInsets} from './react-native-platform/insets.util.js';
+export type {TourContextType} from './shared/types/tour-context.type.js';
+export type {StartTourOptions, TourEndCallback, TourEndInfo, TourEndReason} from './shared/types/tour-end-info.type.js';
+export type {TourI18n} from './shared/types/tour-i18n.type.js';
+export type {TourPlacement, TourStep, TourStepContext, TourTarget} from './shared/types/tour-step.type.js';
+export type {TourTheme} from './shared/types/tour-theme.type.js';
+export type {TourTooltipProps} from './shared/types/tour-tooltip-props.type.js';

package/src/react-platform/dom/elements.util.ts

@@ -0,0 +1,191 @@
+import type {Box} from '../../shared/geometry/geometry.type.js';
+import type {TourTarget} from '../../shared/types/tour-step.type.js';
+
+export function toBox(rect: DOMRectReadOnly): Box {
+  return {x: rect.left, y: rect.top, width: rect.width, height: rect.height};
+}
+
+/**
+ * False in documents without a layout engine (jsdom, happy-dom in test suites): every size there is
+ * zero. A real page always has a size, also a zero-sized frame (its window is zero-sized too).
+ */
+export function hasLayout(): boolean {
+  const root = document.documentElement;
+  return root.clientWidth > 0 || root.clientHeight > 0 || globalThis.innerWidth === 0 || globalThis.innerHeight === 0;
+}
+
+type VisibilityCheck = (options?: {visibilityProperty?: boolean; opacityProperty?: boolean}) => boolean;
+
+/** `checkVisibility()` where the browser has it. */
+export function checkVisibility(
+  element: Element,
+  options: {visibilityProperty?: boolean; opacityProperty?: boolean},
+): boolean | undefined {
+  const check = (element as Element & {checkVisibility?: VisibilityCheck}).checkVisibility;
+  return typeof check === 'function' ? check.call(element, options) : undefined;
+}
+
+/** True when the element takes up space and is not hidden (`display: none`, `visibility: hidden`, closed `<details>`). */
+export function isRendered(element: Element): boolean {
+  if (!hasLayout()) {
+    // Nothing has a size: count every element that is not explicitly hidden.
+    return element.isConnected && !element.closest('[hidden]') && getComputedStyle(element).display !== 'none';
+  }
+
+  const rect = element.getBoundingClientRect();
+  if (rect.width <= 0 && rect.height <= 0) {
+    return false;
+  }
+
+  return checkVisibility(element, {visibilityProperty: true}) ?? getComputedStyle(element).visibility !== 'hidden';
+}
+
+/**
+ * Resolves a target to an element. For selectors, the first rendered match wins, which handles
+ * layouts that duplicate markup (for example a mobile and a desktop navigation).
+ */
+export function resolveTarget(target: TourTarget): Element | undefined {
+  if (typeof target === 'string') {
+    let matches: NodeListOf<Element>;
+    try {
+      matches = document.querySelectorAll(target);
+    } catch {
+      return undefined;
+    }
+
+    for (const element of matches) {
+      if (isRendered(element)) {
+        return element;
+      }
+    }
+
+    return matches[0] ?? undefined;
+  }
+
+  const {current} = target;
+  return current instanceof Element ? current : undefined;
+}
+
+/** The parent element, crossing shadow-root boundaries. */
+export function parentOf(element: Element): Element | undefined {
+  if (element.parentElement) {
+    return element.parentElement;
+  }
+
+  const root = element.getRootNode();
+  return root instanceof ShadowRoot ? root.host : undefined;
+}
+
+/** `ancestor.contains(element)`, also for elements inside shadow roots of the ancestor's descendants. */
+export function containsComposed(ancestor: Element, element: Element): boolean {
+  for (let current: Element | undefined = element; current; current = parentOf(current)) {
+    if (current === ancestor) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * The page's direction. Browsers take it from `<body>` (CSS calls it the principal writing mode),
+ * so `<body dir="rtl">` turns the page right-to-left even when `<html>` is left-to-right.
+ */
+export function pageDirection(): 'ltr' | 'rtl' {
+  const element = document.body ?? document.documentElement;
+  return getComputedStyle(element).direction === 'rtl' ? 'rtl' : 'ltr';
+}
+
+const textInputTypes = new Set([
+  'text',
+  'search',
+  'email',
+  'url',
+  'tel',
+  'password',
+  'number',
+  'date',
+  'datetime-local',
+  'month',
+  'week',
+  'time',
+]);
+
+/** Inputs that a space press activates or toggles. */
+const pressableInputTypes = new Set(['button', 'submit', 'reset', 'image', 'checkbox', 'file', 'color']);
+
+const arrowKeys = new Set(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']);
+const rangeKeys = new Set([...arrowKeys, 'PageUp', 'PageDown', 'Home', 'End']);
+
+/** Widgets whose arrow, page, Home and End keys move a selection or change a value. */
+const keyedWidgetSelector = [
+  'slider',
+  'spinbutton',
+  'radio',
+  'radiogroup',
+  'tab',
+  'tablist',
+  'listbox',
+  'option',
+  'menu',
+  'menubar',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'tree',
+  'treeitem',
+  'treegrid',
+  'grid',
+  'gridcell',
+  'combobox',
+  'textbox',
+  'searchbox',
+  'scrollbar',
+]
+  .map((role) => `[role="${role}"]`)
+  .join(', ');
+
+/** Widgets that a space press activates (links do not: space scrolls the page there). */
+const pressableSelector =
+  'button, summary, [role="button"], [role="checkbox"], [role="switch"], [role="radio"], [role="option"], [role="tab"], [role="treeitem"], [role^="menuitem"]';
+
+/**
+ * True when the focused element handles `key` itself (typing, toggling, choosing, adjusting a
+ * value), so the tour neither navigates nor blocks scrolling with it.
+ */
+export function handlesKey(target: EventTarget | null, key: string): boolean {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  if (
+    target.isContentEditable ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement ||
+    ((target instanceof HTMLAudioElement || target instanceof HTMLVideoElement) && target.controls)
+  ) {
+    return true;
+  }
+
+  if (target instanceof HTMLInputElement) {
+    if (textInputTypes.has(target.type)) {
+      return true;
+    }
+
+    if (target.type === 'radio') {
+      return key === ' ' || arrowKeys.has(key);
+    }
+
+    if (target.type === 'range') {
+      return rangeKeys.has(key);
+    }
+
+    return key === ' ' && pressableInputTypes.has(target.type);
+  }
+
+  if (key === ' ') {
+    return target.closest(pressableSelector) !== null;
+  }
+
+  return rangeKeys.has(key) && target.closest(keyedWidgetSelector) !== null;
+}

package/src/react-platform/dom/occluders.util.ts

@@ -0,0 +1,88 @@
+import {intersect} from '../../shared/geometry/box.util.js';
+import type {Box} from '../../shared/geometry/geometry.type.js';
+import {checkVisibility, containsComposed, toBox} from './elements.util.js';
+
+/**
+ * Elements that stay put while the page scrolls (`position: fixed` or `sticky`): navigation bars,
+ * headers, floating buttons, chat widgets, cookie banners, toasts. Anything scrolled underneath
+ * them is hidden, so the tour scrolls targets clear of them where it can.
+ *
+ * Hit-testing (`elementsFromPoint`) cannot find them while the tour is open: the tour is a modal
+ * dialog and the inert page is excluded from hit-testing. They are found by computed style instead,
+ * also inside open shadow roots (web components). The list is cached briefly so following a
+ * scrolling target does not rescan the page every frame.
+ */
+const rescanAfterMs = 500;
+let cache: {readonly at: number; readonly elements: readonly Element[]} | undefined;
+
+/** Forgets the cached elements, so a page that has been navigated away from is not kept in memory. */
+export function clearOccluderCache(): void {
+  cache = undefined;
+}
+
+function stayingPutElements(layer: Element | undefined): readonly Element[] {
+  const now = performance.now();
+  if (cache && now - cache.at < rescanAfterMs) {
+    return cache.elements;
+  }
+
+  const elements: Element[] = [];
+  const scan = (root: ParentNode): void => {
+    for (const element of root.querySelectorAll('*')) {
+      if (element.shadowRoot) {
+        scan(element.shadowRoot);
+      }
+
+      const {position} = getComputedStyle(element);
+      if (position === 'fixed' || position === 'sticky') {
+        elements.push(element);
+      }
+    }
+  };
+
+  scan(document.body);
+  const found = elements.filter((element) => !layer?.contains(element) && !element.matches('[data-rtk-probe]'));
+  cache = {at: now, elements: found};
+  return found;
+}
+
+/** False for elements that are there but cannot be seen: closed menus faded out with `visibility` or `opacity`. */
+function isSeen(element: Element): boolean {
+  const checked = checkVisibility(element, {visibilityProperty: true, opacityProperty: true});
+  if (checked !== undefined) {
+    return checked;
+  }
+
+  const style = getComputedStyle(element);
+  return style.visibility !== 'hidden' && style.opacity !== '0';
+}
+
+/**
+ * Rectangles (viewport coordinates) of elements that can cover the target. Excluded: elements
+ * containing the target (highlighting a link in a sticky navigation) or inside it, empty or
+ * invisible ones, and ones covering more than half the screen (app shells, full-screen
+ * backgrounds), which cannot be scrolled away from.
+ */
+export function findOccluders(target: Element | undefined, layer: Element | undefined): Box[] {
+  const screen = {width: document.documentElement.clientWidth, height: document.documentElement.clientHeight};
+  const occluders: Box[] = [];
+  for (const element of stayingPutElements(layer)) {
+    if (!element.isConnected || (target && (containsComposed(element, target) || containsComposed(target, element)))) {
+      continue;
+    }
+
+    const rect = toBox(element.getBoundingClientRect());
+    const isCovering =
+      rect.width > 0 && rect.height > 0 && rect.width * rect.height <= (screen.width * screen.height) / 2;
+    if (isCovering && isSeen(element)) {
+      occluders.push(rect);
+    }
+  }
+
+  return occluders;
+}
+
+/** The occluders overlapping `box`. */
+export function occludersOver(box: Box, occluders: readonly Box[]): Box[] {
+  return occluders.filter((occluder) => intersect(occluder, box) !== undefined);
+}