@robertlinde/react-tour-kit 0.8.9 → 1.0.1

package/src/react-platform/dom/scroll-lock.util.ts

@@ -0,0 +1,261 @@
+import {handlesKey, hasLayout} from './elements.util.js';
+import {readPageOverflow} from './scroll.util.js';
+
+function canScroll(element: Element, deltaX: number, deltaY: number): boolean {
+  const style = getComputedStyle(element);
+  const scrollsY = /auto|scroll|overlay/u.test(style.overflowY) && element.scrollHeight > element.clientHeight;
+  const scrollsX = /auto|scroll|overlay/u.test(style.overflowX) && element.scrollWidth > element.clientWidth;
+  if (scrollsY && deltaY !== 0) {
+    const atTop = element.scrollTop <= 0;
+    const atBottom = element.scrollTop + element.clientHeight >= element.scrollHeight - 1;
+    if ((deltaY < 0 && !atTop) || (deltaY > 0 && !atBottom)) {
+      return true;
+    }
+  }
+
+  if (scrollsX && deltaX !== 0) {
+    const max = element.scrollWidth - element.clientWidth;
+    const position = Math.abs(element.scrollLeft);
+    if ((deltaX < 0 && position > 0) || (deltaX > 0 && position < max - 1)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** True when `from` or one of its ancestors (up to `boundary`) can scroll further in the given direction. */
+function canScrollWithin(from: EventTarget | null, boundary: Element, deltaX: number, deltaY: number): boolean {
+  for (
+    let element = from instanceof Element ? from : null;
+    element && element !== boundary;
+    element = element.parentElement
+  ) {
+    if (canScroll(element, deltaX, deltaY)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * The scrollable part of the tooltip (the built-in card's body, or a custom tooltip that does not
+ * fit) that can scroll in the given direction, when the focus is on the tooltip itself: browsers
+ * only scroll the focused element's ancestors with the keyboard, never its descendants.
+ */
+function scrollableInTooltip(from: EventTarget | null, layer: Element, deltaY: number): Element | undefined {
+  const frame =
+    from === layer
+      ? layer.querySelector('[data-rtk-tooltip]:not([data-hidden])')
+      : from instanceof Element
+        ? from.closest('[data-rtk-tooltip]')
+        : null;
+  if (!frame || !(from instanceof Element) || (from !== layer && !frame.contains(from))) {
+    return undefined;
+  }
+
+  return [frame, ...frame.querySelectorAll('*')].find((element) => canScroll(element, 0, deltaY));
+}
+
+/** How far each scrolling key scrolls: pixels, or `page` / `end`. */
+function keyScroll(event: KeyboardEvent): {readonly direction: -1 | 1; readonly amount: number | 'page' | 'end'} {
+  // Ctrl/Cmd with an arrow goes all the way.
+  const arrowAmount = event.ctrlKey || event.metaKey ? 'end' : 40;
+  switch (event.key) {
+    case 'ArrowUp': {
+      return {direction: -1, amount: arrowAmount};
+    }
+
+    case 'ArrowDown': {
+      return {direction: 1, amount: arrowAmount};
+    }
+
+    case 'PageUp': {
+      return {direction: -1, amount: 'page'};
+    }
+
+    case 'Home': {
+      return {direction: -1, amount: 'end'};
+    }
+
+    case 'End': {
+      return {direction: 1, amount: 'end'};
+    }
+
+    default: {
+      // PageDown, and the space bar (with Shift: up).
+      return {direction: event.key === ' ' && event.shiftKey ? -1 : 1, amount: 'page'};
+    }
+  }
+}
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof globalThis.matchMedia === 'function' && globalThis.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+const scrollKeys = new Set(['PageUp', 'PageDown', 'Home', 'End', 'ArrowUp', 'ArrowDown', ' ']);
+
+/** Where smooth keyboard scrolls are heading, so quick presses add up like the browser's own. */
+const keyScrollDestinations = new WeakMap<Element, {readonly top: number; readonly at: number}>();
+const smoothScrollMs = 400;
+
+function scrollByKey(element: Element, direction: -1 | 1, amount: number | 'page' | 'end'): void {
+  const max = element.scrollHeight - element.clientHeight;
+  const pending = keyScrollDestinations.get(element);
+  const from = pending && performance.now() - pending.at < smoothScrollMs ? pending.top : element.scrollTop;
+  const distance = amount === 'end' ? max : amount === 'page' ? element.clientHeight * 0.875 : amount;
+  const top = Math.min(max, Math.max(0, from + direction * distance));
+  const isSmooth = !prefersReducedMotion();
+  keyScrollDestinations.set(element, {top, at: performance.now()});
+  element.scrollTo({top, behavior: isSmooth ? 'smooth' : 'instant'});
+}
+
+type PageLock = {readonly overflow: {readonly x: string; readonly y: string}; readonly release: () => void};
+let pageLock: PageLock | undefined;
+let pageLockUsers = 0;
+
+/** The page's own overflow, also while the tour has locked it. */
+export function pageOverflow(): {readonly x: string; readonly y: string} {
+  return pageLock?.overflow ?? readPageOverflow();
+}
+
+/**
+ * Hides the page's scrollbar (`overflow: hidden` on `<html>`), so it cannot be dragged while the
+ * tour is open; programmatic scrolling still works. Only where that cannot move anything: with
+ * overlay scrollbars, which take no space (macOS, mobile). Hiding a classic scrollbar would widen
+ * the page (browsers drop the space of styled scrollbars even with `scrollbar-gutter: stable`), and
+ * pages cannot block it (the wheel over it scrolls the page whatever its listeners do), so it stays
+ * usable; the tour keeps the target in view when it is used. Pages whose `<body>` has an overflow of
+ * its own, and pinch-zoomed pages, are left alone too.
+ */
+function lockPage(): PageLock {
+  const overflow = readPageOverflow();
+  const root = document.documentElement;
+  const body = document.body ? getComputedStyle(document.body) : undefined;
+  const isRootOverflow =
+    getComputedStyle(root).overflowY !== 'visible' ||
+    !body ||
+    (body.overflowX === 'visible' && body.overflowY === 'visible');
+  const hasClassicScrollbar =
+    globalThis.innerWidth - root.clientWidth > 0.5 || globalThis.innerHeight - root.clientHeight > 0.5;
+  const isZoomed = Math.abs((globalThis.visualViewport?.scale ?? 1) - 1) >= 0.01;
+  if (!hasLayout() || !isRootOverflow || hasClassicScrollbar || isZoomed) {
+    return {
+      overflow,
+      release(): void {
+        // Nothing was changed.
+      },
+    };
+  }
+
+  const hadStyle = root.hasAttribute('style');
+  const previous = ['overflow-x', 'overflow-y'].map(
+    (property) => [property, root.style.getPropertyValue(property), root.style.getPropertyPriority(property)] as const,
+  );
+  root.style.setProperty('overflow-x', 'hidden');
+  root.style.setProperty('overflow-y', 'hidden');
+  return {
+    overflow,
+    release(): void {
+      for (const [property, value, priority] of previous) {
+        if (value) {
+          root.style.setProperty(property, value, priority);
+        } else {
+          root.style.removeProperty(property);
+        }
+      }
+
+      if (!hadStyle && !root.getAttribute('style')) {
+        root.removeAttribute('style');
+      }
+    },
+  };
+}
+
+function acquirePageLock(): () => void {
+  pageLockUsers++;
+  pageLock ??= lockPage();
+  let isReleased = false;
+  return () => {
+    if (isReleased) {
+      return;
+    }
+
+    isReleased = true;
+    pageLockUsers--;
+    if (pageLockUsers === 0) {
+      pageLock?.release();
+      pageLock = undefined;
+    }
+  };
+}
+
+/**
+ * Keeps the page from scrolling while the tour is open (wheel, touch, keyboard, overlay scrollbars), so
+ * the user cannot scroll the highlighted element out of view. Scrolling inside the tooltip still
+ * works, with the keyboard too, and so do keys that controls in the tooltip use themselves.
+ * Programmatic scrolling (the tour's own, or the app's) is not affected. Returns the cleanup.
+ */
+export function lockScroll(layer: HTMLElement): () => void {
+  let touchX = 0;
+  let touchY = 0;
+  const releasePage = acquirePageLock();
+  const onWheel = (event: WheelEvent): void => {
+    if (!event.ctrlKey && !canScrollWithin(event.target, layer, event.deltaX, event.deltaY)) {
+      event.preventDefault();
+    }
+  };
+
+  const onTouchStart = (event: TouchEvent): void => {
+    const touch = event.touches[0];
+    if (touch) {
+      touchX = touch.clientX;
+      touchY = touch.clientY;
+    }
+  };
+
+  const onTouchMove = (event: TouchEvent): void => {
+    const touch = event.touches[0];
+    // Two fingers: pinch-zoom stays available.
+    if (!touch || event.touches.length > 1) {
+      return;
+    }
+
+    if (!canScrollWithin(event.target, layer, touchX - touch.clientX, touchY - touch.clientY)) {
+      event.preventDefault();
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (!scrollKeys.has(event.key) || event.defaultPrevented || handlesKey(event.target, event.key)) {
+      return;
+    }
+
+    const {direction, amount} = keyScroll(event);
+    if (canScrollWithin(event.target, layer, 0, direction)) {
+      // The browser scrolls the focused element's scrollable ancestor.
+      return;
+    }
+
+    event.preventDefault();
+    const scrollable = scrollableInTooltip(event.target, layer, direction);
+    if (scrollable) {
+      scrollByKey(scrollable, direction, amount);
+    }
+  };
+
+  layer.addEventListener('wheel', onWheel, {passive: false});
+  layer.addEventListener('touchstart', onTouchStart, {passive: true});
+  layer.addEventListener('touchmove', onTouchMove, {passive: false});
+  layer.addEventListener('keydown', onKeyDown);
+  return () => {
+    releasePage();
+    layer.removeEventListener('wheel', onWheel);
+    layer.removeEventListener('touchstart', onTouchStart);
+    layer.removeEventListener('touchmove', onTouchMove);
+    layer.removeEventListener('keydown', onKeyDown);
+  };
+}

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

@@ -0,0 +1,310 @@
+import {deflate, narrowClip} from '../../shared/geometry/box.util.js';
+import type {Box, Insets, Point} from '../../shared/geometry/geometry.type.js';
+import type {ScrollContainer, ScrollContainerMetrics, ScrollOptions} from '../../shared/platform/platform.type.js';
+import {requestFrame} from '../../shared/utils/frame.util.js';
+import {pageDirection, parentOf} from './elements.util.js';
+import {occludersOver} from './occluders.util.js';
+import {readViewport} from './viewport.util.js';
+
+const clippingOverflow = new Set(['hidden', 'scroll', 'auto', 'overlay', 'clip']);
+/**
+ * Overflow the user can scroll. `hidden` only clips: what it shows is up to the app (carousels,
+ * sliders, off-canvas menus), so the tour never scrolls it.
+ */
+const userScrollable = new Set(['scroll', 'auto', 'overlay']);
+
+/** Which axes of a scroll container the tour may scroll. */
+export type ScrollAxes = {readonly x: boolean; readonly y: boolean};
+
+/**
+ * True for elements whose overflow is the page's (CSS overflow propagation): `<html>`, and `<body>`
+ * unless `<html>` has an overflow of its own (then `<body>` is a scroll container like any other).
+ */
+function holdsPageOverflow(element: Element): boolean {
+  if (element === document.documentElement) {
+    return true;
+  }
+
+  return element === document.body && getComputedStyle(document.documentElement).overflowY === 'visible';
+}
+
+/** The page's own overflow per axis (from `<html>`, or from `<body>` when `<html>` has none). */
+export function readPageOverflow(): {readonly x: string; readonly y: string} {
+  const root = getComputedStyle(document.documentElement);
+  const style = root.overflowY === 'visible' && document.body ? getComputedStyle(document.body) : root;
+  return {x: style.overflowX, y: style.overflowY};
+}
+
+function isSet(value: string): boolean {
+  return value !== '' && value !== 'none';
+}
+
+/**
+ * True when an element with `style` is the containing block of `position: absolute` (or `fixed`)
+ * descendants: their position, clipping and scrolling come from it, not from the elements between.
+ */
+function isContainingBlock(style: CSSStyleDeclaration, of: 'absolute' | 'fixed'): boolean {
+  if (of === 'absolute' && style.position !== 'static') {
+    return true;
+  }
+
+  return (
+    ['transform', 'translate', 'rotate', 'scale', 'perspective', 'filter', 'backdrop-filter'].some((property) =>
+      isSet(style.getPropertyValue(property)),
+    ) ||
+    /layout|paint|strict|content/u.test(style.getPropertyValue('contain')) ||
+    /transform|translate|rotate|scale|perspective|filter/u.test(style.getPropertyValue('will-change')) ||
+    !['', 'normal'].includes(style.getPropertyValue('container-type')) ||
+    style.getPropertyValue('content-visibility') === 'auto'
+  );
+}
+
+function escapeOf(position: string): 'absolute' | 'fixed' | undefined {
+  return position === 'absolute' || position === 'fixed' ? position : undefined;
+}
+
+function paddingBox(element: Element): Box {
+  const rect = element.getBoundingClientRect();
+  return {
+    x: rect.left + element.clientLeft,
+    y: rect.top + element.clientTop,
+    width: element.clientWidth,
+    height: element.clientHeight,
+  };
+}
+
+/** A computed length (`20px`, `10%`, `calc(10% + 20px)`) in pixels; percentages refer to `basis`. */
+export function resolveLength(value: string, basis: number): number {
+  const expression = value.startsWith('calc(') && value.endsWith(')') ? value.slice(5, -1) : value;
+  let total = 0;
+  let sign = 1;
+  for (const token of expression.trim().split(/\s+/u)) {
+    if (token === '+' || token === '-') {
+      sign = token === '-' ? -1 : 1;
+      continue;
+    }
+
+    const match = /^(-?[\d.]+(?:e[+-]?\d+)?)(px|%)$/iu.exec(token);
+    if (!match?.[1]) {
+      // `auto`, or an expression this does not understand.
+      return Number.parseFloat(value) || 0;
+    }
+
+    const amount = Number(match[1]);
+    total += sign * (match[2] === '%' ? (amount / 100) * basis : amount);
+  }
+
+  return Number.isFinite(total) ? total : 0;
+}
+
+function scrollPadding(element: Element, size: {readonly width: number; readonly height: number}): Insets {
+  const style = getComputedStyle(element);
+  return {
+    top: resolveLength(style.scrollPaddingTop, size.height),
+    right: resolveLength(style.scrollPaddingRight, size.width),
+    bottom: resolveLength(style.scrollPaddingBottom, size.height),
+    left: resolveLength(style.scrollPaddingLeft, size.width),
+  };
+}
+
+type Ancestors = {
+  /** Scroll containers that move the target, innermost first (the page itself is not included). */
+  readonly scrollers: ReadonlyArray<{readonly element: Element; readonly axes: ScrollAxes}>;
+  /** Intersection of every clipping ancestor's padding box, or `undefined` when nothing clips. */
+  readonly clip: Box | undefined;
+  /** True when the target sits inside a `position: fixed` element, so scrolling the page does not move it. */
+  readonly fixed: boolean;
+};
+
+/**
+ * Walks up from `element`, collecting the scroll containers and clipping that apply to it. An
+ * absolutely positioned element escapes the overflow of the ancestors between it and its
+ * containing block (a dropdown sticking out of a navigation bar); a fixed one escapes everything
+ * up to the page.
+ */
+export function inspectAncestors(element: Element): Ancestors {
+  const scrollers: Array<{element: Element; axes: ScrollAxes}> = [];
+  let clip: Box | undefined;
+  let escaping = escapeOf(getComputedStyle(element).position);
+  for (let current = parentOf(element); current && current !== document.documentElement; current = parentOf(current)) {
+    if (holdsPageOverflow(current)) {
+      continue;
+    }
+
+    const style = getComputedStyle(current);
+    if (escaping) {
+      if (!isContainingBlock(style, escaping)) {
+        continue;
+      }
+
+      escaping = undefined;
+    }
+
+    const clips = clippingOverflow.has(style.overflowX) || clippingOverflow.has(style.overflowY);
+    // `display: contents` elements have no box, so their overflow does nothing.
+    if (clips && style.display !== 'contents') {
+      clip = narrowClip(clip, paddingBox(current));
+      const axes = {
+        x: userScrollable.has(style.overflowX) && current.scrollWidth > current.clientWidth + 1,
+        y: userScrollable.has(style.overflowY) && current.scrollHeight > current.clientHeight + 1,
+      };
+      if (axes.x || axes.y) {
+        scrollers.push({element: current, axes});
+      }
+    }
+
+    escaping = escapeOf(style.position);
+  }
+
+  return {scrollers, clip, fixed: escaping === 'fixed'};
+}
+
+function isRtl(element: Element): boolean {
+  return getComputedStyle(element).direction === 'rtl';
+}
+
+/** Where the tour may scroll on each axis: from 0 to the end where it may, nowhere where it must not. */
+function scrollRange(
+  offset: Point,
+  max: Point,
+  axes: ScrollAxes,
+): Pick<ScrollContainerMetrics, 'minOffset' | 'maxOffset'> {
+  return {
+    minOffset: {x: axes.x ? 0 : offset.x, y: axes.y ? 0 : offset.y},
+    maxOffset: {x: axes.x ? max.x : offset.x, y: axes.y ? max.y : offset.y},
+  };
+}
+
+/** A nested scroll container. Horizontal offsets are normalised to [0, max] in right-to-left containers too. */
+export function elementContainer(element: Element, axes: ScrollAxes, occluders: () => readonly Box[]): ScrollContainer {
+  const maxX = (): number => Math.max(0, element.scrollWidth - element.clientWidth);
+  const read = (): Point => ({
+    x: isRtl(element) ? element.scrollLeft + maxX() : element.scrollLeft,
+    y: element.scrollTop,
+  });
+  return {
+    async measure(): Promise<ScrollContainerMetrics | undefined> {
+      if (!element.isConnected) {
+        return undefined;
+      }
+
+      const box = paddingBox(element);
+      const area = deflate(box, scrollPadding(element, box));
+      const offset = read();
+      return {
+        area,
+        obstacles: occludersOver(area, occluders()),
+        offset,
+        ...scrollRange(offset, {x: maxX(), y: Math.max(0, element.scrollHeight - element.clientHeight)}, axes),
+      };
+    },
+    async scrollTo(offset, options): Promise<void> {
+      element.scrollTo({
+        left: isRtl(element) ? offset.x - maxX() : offset.x,
+        top: offset.y,
+        behavior: options.animated ? 'smooth' : 'instant',
+      });
+      await waitForScrollEnd(element, read, offset, options);
+    },
+  };
+}
+
+/**
+ * The page itself; its visible area is the visual viewport minus safe areas and the page's
+ * scroll-padding. `overflow` is the page's own (see `readPageOverflow`), not the tour's scroll lock.
+ */
+export function pageContainer(
+  occluders: () => readonly Box[],
+  overflow: {readonly x: string; readonly y: string},
+): ScrollContainer {
+  const root = (): Element => document.scrollingElement ?? document.documentElement;
+  const maxX = (): number => Math.max(0, root().scrollWidth - root().clientWidth);
+  const read = (): Point => ({
+    x: pageDirection() === 'rtl' ? globalThis.scrollX + maxX() : globalThis.scrollX,
+    y: globalThis.scrollY,
+  });
+  // The page scrolls unless the app keeps an axis from scrolling (`overflow-x: hidden` against
+  // stray horizontal overflow, off-canvas menus): then the tour leaves that axis alone too.
+  const axes = {x: !['hidden', 'clip'].includes(overflow.x), y: !['hidden', 'clip'].includes(overflow.y)};
+  return {
+    async measure(): Promise<ScrollContainerMetrics | undefined> {
+      const viewport = readViewport();
+      const visible = deflate(viewport.rect, viewport.insets);
+      const size = {width: document.documentElement.clientWidth, height: document.documentElement.clientHeight};
+      const offset = read();
+      return {
+        area: deflate(visible, scrollPadding(document.documentElement, size)),
+        // Sticky headers, floating buttons, banners: the target is scrolled clear of them where possible.
+        obstacles: occluders(),
+        offset,
+        ...scrollRange(offset, {x: maxX(), y: Math.max(0, root().scrollHeight - root().clientHeight)}, axes),
+      };
+    },
+    async scrollTo(offset, options): Promise<void> {
+      globalThis.scrollTo({
+        left: pageDirection() === 'rtl' ? offset.x - maxX() : offset.x,
+        top: offset.y,
+        behavior: options.animated ? 'smooth' : 'instant',
+      });
+      await waitForScrollEnd(globalThis, read, offset, options);
+    },
+  };
+}
+
+/** Frames without movement after which a smooth scroll counts as finished (it moved, or it never started). */
+const stillFramesAfterMoving = 3;
+const stillFramesWithoutMoving = 8;
+
+/**
+ * Resolves once a scroll of `scroller` has finished: at `scrollend` where browsers support it, or
+ * once the offset has reached `requested`, or has stopped changing (scroll snapping can end the
+ * scroll elsewhere). Instant scrolls finish on the next frame.
+ */
+async function waitForScrollEnd(
+  scroller: EventTarget,
+  read: () => Point,
+  requested: Point,
+  {animated, signal}: ScrollOptions,
+): Promise<void> {
+  if (signal.aborted) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    let cancelFrame: () => void;
+    let previous = read();
+    let stillFrames = 0;
+    let hasMoved = false;
+    const finish = (): void => {
+      cancelFrame();
+      scroller.removeEventListener('scrollend', finish);
+      signal.removeEventListener('abort', finish);
+      resolve();
+    };
+
+    const tick = (): void => {
+      const current = read();
+      const isStill = Math.abs(current.x - previous.x) < 0.5 && Math.abs(current.y - previous.y) < 0.5;
+      hasMoved ||= !isStill;
+      stillFrames = isStill ? stillFrames + 1 : 0;
+      previous = current;
+      const hasArrived = Math.abs(current.x - requested.x) <= 1 && Math.abs(current.y - requested.y) <= 1;
+      const isDone =
+        !animated ||
+        (hasArrived && isStill) ||
+        stillFrames >= (hasMoved ? stillFramesAfterMoving : stillFramesWithoutMoving);
+      if (isDone) {
+        finish();
+      } else {
+        cancelFrame = requestFrame(tick);
+      }
+    };
+
+    if (animated) {
+      scroller.addEventListener('scrollend', finish);
+    }
+
+    signal.addEventListener('abort', finish);
+    cancelFrame = requestFrame(tick);
+  });
+}

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

@@ -0,0 +1,74 @@
+import {zeroInsets} from '../../shared/geometry/box.util.js';
+import type {Box, Insets, Viewport} from '../../shared/geometry/geometry.type.js';
+
+let probe: HTMLElement | undefined;
+
+/**
+ * Safe-area insets (notch, home indicator) via `env(safe-area-inset-*)`. They are only non-zero
+ * when the page opts in with `viewport-fit=cover`.
+ */
+export function readSafeAreaInsets(): Insets {
+  if (typeof document === 'undefined' || !document.body) {
+    return zeroInsets;
+  }
+
+  if (!probe?.isConnected) {
+    probe = document.createElement('div');
+    probe.setAttribute('aria-hidden', 'true');
+    probe.dataset.rtkProbe = '';
+    probe.style.cssText =
+      'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;pointer-events:none;' +
+      'padding:env(safe-area-inset-top,0px) env(safe-area-inset-right,0px) env(safe-area-inset-bottom,0px) env(safe-area-inset-left,0px)';
+    document.body.append(probe);
+  }
+
+  const style = getComputedStyle(probe);
+  return {
+    top: Number.parseFloat(style.paddingTop) || 0,
+    right: Number.parseFloat(style.paddingRight) || 0,
+    bottom: Number.parseFloat(style.paddingBottom) || 0,
+    left: Number.parseFloat(style.paddingLeft) || 0,
+  };
+}
+
+let probeUsers = 0;
+
+/** Registers a user of the safe-area probe; the returned function releases it and removes the probe when unused. */
+export function acquireSafeAreaProbe(): () => void {
+  probeUsers++;
+  return () => {
+    probeUsers--;
+    if (probeUsers === 0) {
+      probe?.remove();
+      probe = undefined;
+    }
+  };
+}
+
+/**
+ * The part of the page the user sees, in the coordinate space of `position: fixed` elements
+ * (the layout viewport): the visual viewport (pinch-zoom, on-screen keyboard), without scrollbars.
+ */
+export function readVisibleRect(): Box {
+  const root = document.documentElement;
+  const layoutWidth = root.clientWidth || window.innerWidth;
+  const layoutHeight = root.clientHeight || window.innerHeight;
+  const visual = window.visualViewport;
+  if (!visual) {
+    return {x: 0, y: 0, width: layoutWidth, height: layoutHeight};
+  }
+
+  const x = Math.max(0, visual.offsetLeft);
+  const y = Math.max(0, visual.offsetTop);
+  return {
+    x,
+    y,
+    width: Math.max(0, Math.min(visual.width, layoutWidth - x)),
+    height: Math.max(0, Math.min(visual.height, layoutHeight - y)),
+  };
+}
+
+/** The visible area and its safe-area insets (notch, home indicator). */
+export function readViewport(): Viewport {
+  return {rect: readVisibleRect(), insets: readSafeAreaInsets()};
+}