@robertlinde/react-tour-kit 0.8.9 → 1.0.1

package/src/react-platform/dom/web-platform.ts

@@ -0,0 +1,208 @@
+import type {TargetMeasurement} from '../../shared/engine/tour-adapter.type.js';
+import type {ExternalValue, PlatformAdapter, ScrollContainer} from '../../shared/platform/platform.type.js';
+import type {TourTarget} from '../../shared/types/tour-step.type.js';
+import {hasLayout, isRendered, resolveTarget, toBox} from './elements.util.js';
+import {clearOccluderCache, findOccluders, occludersOver} from './occluders.util.js';
+import {pageOverflow} from './scroll-lock.util.js';
+import {elementContainer, inspectAncestors, pageContainer} from './scroll.util.js';
+import {readViewport} from './viewport.util.js';
+
+export type WebPlatform = PlatformAdapter & {
+  /**
+   * Adds the element the tour is drawn into at the end of `<body>`. Its changes are ignored, it is
+   * skipped when looking for elements covering the target, and its pointer, focus and key events
+   * stay inside it. Returns the element to render into and the cleanup.
+   */
+  readonly mountHost: () => {readonly container: HTMLElement; readonly unmount: () => void};
+};
+
+/**
+ * Events that must not reach the app's listeners on `<body>`, `document` or `window`: "click
+ * outside" handlers of menus and popovers (which would close the menu a step highlights), focus
+ * traps of the app's own dialogs, and keyboard shortcuts. The page is inert while the tour is
+ * open, so nothing in it expects them.
+ */
+const isolatedEvents = [
+  'pointerdown',
+  'pointerup',
+  'mousedown',
+  'mouseup',
+  'touchstart',
+  'touchend',
+  'click',
+  'dblclick',
+  'auxclick',
+  'contextmenu',
+  'focusin',
+  'focusout',
+  'keydown',
+  'keyup',
+] as const;
+
+/** Where a target is reported in documents without layout (jsdom), so tours still run in tests: at the top of the screen. */
+const placeholderRect = {x: 0, y: 0, width: 1, height: 1};
+
+function measureElement(element: Element, host: Element | undefined): TargetMeasurement | undefined {
+  if (!element.isConnected || !isRendered(element)) {
+    return undefined;
+  }
+
+  if (!hasLayout()) {
+    return {rect: placeholderRect, clip: undefined, occluders: []};
+  }
+
+  const rect = toBox(element.getBoundingClientRect());
+  return {rect, clip: inspectAncestors(element).clip, occluders: occludersOver(rect, findOccluders(element, host))};
+}
+
+/** `prefers-reduced-motion`, live. */
+function reducedMotionQuery(): ExternalValue<boolean> {
+  const query =
+    typeof globalThis.matchMedia === 'function' ? globalThis.matchMedia('(prefers-reduced-motion: reduce)') : undefined;
+  return {
+    get: () => query?.matches ?? false,
+    subscribe(listener) {
+      query?.addEventListener('change', listener);
+      return () => {
+        query?.removeEventListener('change', listener);
+      };
+    },
+  };
+}
+
+/** The web's raw facts for the tour: measuring elements, layout events, scroll containers, the visible area. */
+export function createWebPlatform(): WebPlatform {
+  let host: HTMLElement | undefined;
+  const isOwnNode = (node: Node): boolean => host?.contains(node) ?? false;
+  const measureTarget = (target: TourTarget): TargetMeasurement | undefined => {
+    const element = resolveTarget(target);
+    return element ? measureElement(element, host) : undefined;
+  };
+
+  return {
+    async measure(target): Promise<TargetMeasurement | undefined> {
+      return measureTarget(target);
+    },
+
+    subscribe(target, onChange): () => void {
+      // Size changes of the page and of the target (also elements that exist but have no size yet:
+      // expanding drawers, entrance transitions). Selector targets can be replaced by a new element.
+      const resize =
+        typeof ResizeObserver === 'function'
+          ? new ResizeObserver(() => {
+              onChange();
+            })
+          : undefined;
+      resize?.observe(document.documentElement);
+      let observed: Element | undefined;
+      const follow = (): void => {
+        const next = target === undefined ? undefined : resolveTarget(target);
+        if (next !== observed) {
+          if (observed) {
+            resize?.unobserve(observed);
+          }
+
+          observed = next;
+          if (next) {
+            resize?.observe(next);
+          }
+        }
+      };
+
+      const notify = (): void => {
+        follow();
+        onChange();
+      };
+
+      follow();
+      // Content inserted, removed or restyled anywhere (except the tour itself) can move the target.
+      const mutations = new MutationObserver((records) => {
+        if (records.some((record) => !isOwnNode(record.target))) {
+          notify();
+        }
+      });
+      mutations.observe(document.documentElement, {childList: true, subtree: true, attributes: true});
+      const visual = globalThis.visualViewport;
+      globalThis.addEventListener('scroll', notify, {capture: true, passive: true});
+      globalThis.addEventListener('resize', notify, {passive: true});
+      visual?.addEventListener('resize', notify, {passive: true});
+      visual?.addEventListener('scroll', notify, {passive: true});
+      document.addEventListener('transitionend', notify, true);
+      document.addEventListener('animationend', notify, true);
+      return () => {
+        resize?.disconnect();
+        mutations.disconnect();
+        globalThis.removeEventListener('scroll', notify, {capture: true});
+        globalThis.removeEventListener('resize', notify);
+        visual?.removeEventListener('resize', notify);
+        visual?.removeEventListener('scroll', notify);
+        document.removeEventListener('transitionend', notify, true);
+        document.removeEventListener('animationend', notify, true);
+        clearOccluderCache();
+      };
+    },
+
+    // Layout is always announced: by the ResizeObserver above (or, without one, by the other events).
+    isAwaitingLayout: () => false,
+
+    async scrollContainers(target): Promise<readonly ScrollContainer[]> {
+      const element = resolveTarget(target);
+      if (!element || !hasLayout()) {
+        return [];
+      }
+
+      const occluders = (): ReturnType<typeof findOccluders> => findOccluders(element, host);
+      const ancestors = inspectAncestors(element);
+      const containers = ancestors.scrollers.map((scroller) =>
+        elementContainer(scroller.element, scroller.axes, occluders),
+      );
+      // Inside a `position: fixed` element, scrolling the page does not move the target.
+      return ancestors.fixed ? containers : [...containers, pageContainer(occluders, pageOverflow())];
+    },
+
+    getViewport: readViewport,
+
+    reducedMotion: reducedMotionQuery(),
+
+    measuresWhileScrolling: true,
+
+    getPixelRatio: (): number => globalThis.devicePixelRatio || 1,
+
+    mountHost(): {readonly container: HTMLElement; readonly unmount: () => void} {
+      const element = document.createElement('div');
+      element.dataset.rtkHost = '';
+      // No box of its own: the page's layout (flex or grid `<body>`, `:last-child` rules) stays as it is.
+      element.style.display = 'contents';
+      // React listens for events on the element it renders into: keep that one inside, so the tour's
+      // own handlers run before the events are stopped here.
+      const container = document.createElement('div');
+      container.style.display = 'contents';
+      element.append(container);
+      const stop = (event: Event): void => {
+        event.stopPropagation();
+      };
+
+      for (const type of isolatedEvents) {
+        element.addEventListener(type, stop);
+      }
+
+      document.body.append(element);
+      host = element;
+      return {
+        container,
+        unmount(): void {
+          for (const type of isolatedEvents) {
+            element.removeEventListener(type, stop);
+          }
+
+          element.remove();
+          if (host === element) {
+            host = undefined;
+          }
+
+          clearOccluderCache();
+        },
+      };
+    },
+  };
+}

package/src/react-platform/layer/styles.ts

@@ -0,0 +1,286 @@
+/**
+ * Styles of the web tour layer. Everything is scoped to `rtk-` classes. Theme values arrive as
+ * CSS variables set on `.rtk-root`. All rules live in a cascade layer, so the app's own CSS wins
+ * over them without `!important` — except for the few properties marked `!important` here: what
+ * keeps the tour in place, clickable and readable, which global resets (Tailwind's preflight,
+ * normalize.css, Bootstrap, `dialog {…}` or `button {…}` rules) would otherwise change. Those
+ * still follow the CSS variables.
+ */
+export const tourCss = `
+@layer react-tour-kit {
+:where(.rtk-root) {
+  --rtk-primary: #2563eb;
+  --rtk-on-primary: #ffffff;
+  --rtk-bg: #ffffff;
+  --rtk-title: #111827;
+  --rtk-text: #4b5563;
+  --rtk-overlay: rgba(0, 0, 0, 0.5);
+  --rtk-radius: 12px;
+  --rtk-spotlight-radius: 8px;
+  --rtk-ease: cubic-bezier(0.2, 0, 0, 1);
+  --rtk-z-index: 2147483000;
+}
+
+.rtk-root {
+  position: fixed !important;
+  inset: 0 !important;
+  box-sizing: border-box !important;
+  width: 100% !important;
+  height: 100% !important;
+  max-width: none !important;
+  max-height: none !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  color: var(--rtk-text);
+  overflow: visible !important;
+  outline: none;
+  transform: none !important;
+  filter: none !important;
+  /* The page may have disabled pointer events on <body> (modal libraries do while open). */
+  pointer-events: auto !important;
+  z-index: var(--rtk-z-index) !important;
+  opacity: 0 !important;
+  transition: opacity var(--rtk-fade-duration, 200ms) var(--rtk-ease);
+}
+.rtk-root::backdrop { background: transparent !important; backdrop-filter: none !important; }
+.rtk-root[data-visible] { opacity: 1 !important; }
+
+.rtk-backdrop { position: fixed !important; inset: 0 !important; touch-action: pinch-zoom; }
+.rtk-backdrop[data-closable] { cursor: pointer; }
+
+.rtk-spotlight {
+  /* Its geometry is set inline, which an \`!important\` rule here would override. */
+  position: fixed !important;
+  right: auto;
+  bottom: auto;
+  margin: 0 !important;
+  box-sizing: border-box !important;
+  padding: 0 !important;
+  border: 0 !important;
+  pointer-events: none !important;
+  border-radius: var(--rtk-spotlight-radius);
+  box-shadow: 0 0 0 2px var(--rtk-primary), 0 0 0 200vmax var(--rtk-overlay);
+  box-shadow: 0 0 0 2px var(--rtk-primary), 0 0 0 6px color-mix(in srgb, var(--rtk-primary) 30%, transparent), 0 0 0 200vmax var(--rtk-overlay);
+}
+.rtk-spotlight[data-collapsed] { box-shadow: 0 0 0 200vmax var(--rtk-overlay); }
+
+.rtk-tooltip {
+  position: fixed !important;
+  top: 0 !important;
+  left: 0 !important;
+  margin: 0 !important;
+  box-sizing: border-box;
+  display: flow-root;
+  outline: none;
+  overflow: visible;
+  transform-origin: var(--rtk-origin, center);
+}
+.rtk-tooltip[data-overflowing] { overflow: auto; overscroll-behavior: contain; }
+.rtk-tooltip[data-hidden] { visibility: hidden; }
+.rtk-tooltip[data-entering] {
+  animation: rtk-enter var(--rtk-enter-duration, 200ms) var(--rtk-ease) var(--rtk-enter-delay, 0ms) both;
+}
+.rtk-measure {
+  position: fixed !important;
+  top: 0 !important;
+  left: 0 !important;
+  visibility: hidden !important;
+  pointer-events: none !important;
+  box-sizing: border-box;
+  display: flow-root;
+}
+
+.rtk-card {
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: 380px;
+  max-width: 100%;
+  max-height: var(--rtk-max-height, none);
+  border-radius: var(--rtk-radius);
+  background: var(--rtk-bg);
+  color: var(--rtk-text);
+  box-shadow: 0 12px 32px -8px rgba(15, 23, 42, 0.35), 0 4px 12px -6px rgba(15, 23, 42, 0.2);
+  font-size: 14px;
+  line-height: 1.5;
+  text-align: start;
+}
+.rtk-arrow {
+  position: absolute;
+  width: 10px;
+  height: 10px;
+  background: var(--rtk-bg);
+  transform: rotate(45deg);
+}
+.rtk-arrow[data-side="bottom"] { top: -5px; left: calc(var(--rtk-arrow-offset) - 5px); }
+.rtk-arrow[data-side="top"] { bottom: -5px; left: calc(var(--rtk-arrow-offset) - 5px); }
+.rtk-arrow[data-side="right"] { left: -5px; top: calc(var(--rtk-arrow-offset) - 5px); }
+.rtk-arrow[data-side="left"] { right: -5px; top: calc(var(--rtk-arrow-offset) - 5px); }
+
+.rtk-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 8px 0 16px;
+}
+.rtk-counter {
+  border-radius: 999px;
+  padding: 2px 10px;
+  background: var(--rtk-primary);
+  color: var(--rtk-on-primary);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1.6;
+  font-variant-numeric: tabular-nums;
+}
+.rtk-close {
+  position: relative;
+  display: grid;
+  place-items: center;
+  box-sizing: border-box !important;
+  width: 32px !important;
+  height: 32px !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  border-radius: 8px;
+  background: transparent !important;
+  color: var(--rtk-text) !important;
+  cursor: pointer;
+}
+.rtk-close::before, .rtk-button--prev::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background: currentColor;
+  opacity: 0;
+  transition: opacity 120ms;
+}
+.rtk-close:hover::before { opacity: 0.1; }
+.rtk-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  padding: 8px 16px 16px;
+}
+.rtk-title { margin: 0 0 4px; color: var(--rtk-title); font-size: 17px; font-weight: 600; line-height: 1.35; }
+.rtk-content { margin: 0; overflow-wrap: anywhere; }
+.rtk-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 0 16px 16px;
+}
+.rtk-button {
+  position: relative;
+  box-sizing: border-box !important;
+  min-height: 36px !important;
+  margin: 0 !important;
+  padding: 8px 14px !important;
+  border: 0 !important;
+  border-radius: 8px;
+  font-family: inherit;
+  font-size: 14px !important;
+  font-weight: 500 !important;
+  line-height: 1.4 !important;
+  cursor: pointer;
+  white-space: nowrap;
+}
+.rtk-button--prev { background: transparent !important; color: var(--rtk-text) !important; }
+.rtk-button--prev::before { opacity: 0.08; }
+.rtk-button--prev:hover:not(:disabled)::before { opacity: 0.14; }
+.rtk-button--next { background: var(--rtk-primary) !important; color: var(--rtk-on-primary) !important; }
+.rtk-button--next:hover { filter: brightness(1.08); }
+.rtk-button:disabled { cursor: default; opacity: 0.4; }
+.rtk-dots { display: flex; align-items: center; justify-content: center; min-width: 0; }
+.rtk-dot, .rtk-ellipsis {
+  position: relative;
+  display: grid;
+  place-items: center;
+  box-sizing: border-box !important;
+  width: 24px !important;
+  height: 24px !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  background: transparent !important;
+  color: var(--rtk-text) !important;
+}
+.rtk-dot { cursor: pointer; border-radius: 50%; }
+.rtk-dot::before {
+  content: '';
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.3;
+  transition: opacity 150ms, transform 150ms;
+}
+.rtk-dot[aria-current="step"] { color: var(--rtk-primary) !important; }
+.rtk-dot[aria-current="step"]::before { opacity: 1; transform: scale(1.15); }
+.rtk-ellipsis::before { content: '…'; opacity: 0.5; font-size: 12px; letter-spacing: 1px; }
+.rtk-close:focus-visible, .rtk-button:focus-visible, .rtk-dot:focus-visible {
+  outline: 2px solid var(--rtk-primary);
+  outline-offset: 2px;
+}
+.rtk-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* Position uses the individual \`translate\` property (applied first), the entrance uses \`transform\`,
+   so scaling happens around the tooltip's own centre and never moves its position. Durations,
+   offsets and reduced motion come from the shared motion settings, as variables. */
+@keyframes rtk-enter {
+  from {
+    opacity: 0;
+    transform: translate(var(--rtk-enter-x, 0), var(--rtk-enter-y, 0)) scale(var(--rtk-enter-scale, 1));
+  }
+}
+
+@media (forced-colors: active) {
+  .rtk-spotlight { outline: 3px solid Highlight; }
+  .rtk-card { border: 1px solid CanvasText; }
+  /* 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; }
+  .rtk-dot::before { background: CanvasText; }
+  .rtk-dot[aria-current="step"]::before { background: Highlight; }
+}
+}
+`;
+
+const injected = new WeakSet<Document>();
+
+/** Adds the stylesheet to a document once. Constructable stylesheets are not subject to CSP `style-src` restrictions. */
+export function injectTourStyles(document_: Document): void {
+  if (injected.has(document_)) {
+    return;
+  }
+
+  injected.add(document_);
+  try {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(tourCss);
+    document_.adoptedStyleSheets = [...document_.adoptedStyleSheets, sheet];
+  } catch {
+    const style = document_.createElement('style');
+    style.dataset.rtk = '';
+    style.textContent = tourCss;
+    document_.head.append(style);
+  }
+}