@robertlinde/react-tour-kit 0.8.8 → 1.0.0

package/src/shared/geometry/box.util.ts

@@ -0,0 +1,185 @@
+import type {Box, Insets, Point, Size} from './geometry.type.js';
+
+export const zeroInsets: Insets = {top: 0, right: 0, bottom: 0, left: 0};
+
+/** Returns `value` if it is a finite number, otherwise `fallback`. */
+export function finiteOr(value: number, fallback: number): number {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+/** Finite and non-negative, otherwise 0. */
+export function nonNegative(value: number): number {
+  return Math.max(0, finiteOr(value, 0));
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+export function right(box: Box): number {
+  return box.x + box.width;
+}
+
+export function bottom(box: Box): number {
+  return box.y + box.height;
+}
+
+export function centerX(box: Box): number {
+  return box.x + box.width / 2;
+}
+
+export function centerY(box: Box): number {
+  return box.y + box.height / 2;
+}
+
+/**
+ * Coordinates beyond this magnitude are clamped so that sums of coordinates and sizes can never
+ * overflow to `Infinity`. No real screen comes anywhere near it.
+ */
+const coordinateLimit = 1e9;
+
+function coordinate(value: number): number {
+  return clamp(finiteOr(value, 0), -coordinateLimit, coordinateLimit);
+}
+
+export function sanitizeLength(value: number): number {
+  return Math.min(nonNegative(value), coordinateLimit);
+}
+
+/** Replaces non-finite coordinates with 0, negative sizes with 0 and clamps absurd magnitudes. */
+export function sanitizeBox(box: Box): Box {
+  return {
+    x: coordinate(box.x),
+    y: coordinate(box.y),
+    width: sanitizeLength(box.width),
+    height: sanitizeLength(box.height),
+  };
+}
+
+export function sanitizeSize(size: Size): Size {
+  return {width: sanitizeLength(size.width), height: sanitizeLength(size.height)};
+}
+
+export function sanitizeInsets(insets: Insets): Insets {
+  return {
+    top: sanitizeLength(insets.top),
+    right: sanitizeLength(insets.right),
+    bottom: sanitizeLength(insets.bottom),
+    left: sanitizeLength(insets.left),
+  };
+}
+
+export function isFiniteBox(box: Box): boolean {
+  return Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height);
+}
+
+export function inflate(box: Box, amount: number): Box {
+  return {x: box.x - amount, y: box.y - amount, width: box.width + amount * 2, height: box.height + amount * 2};
+}
+
+export function deflate(box: Box, insets: Insets): Box {
+  return {
+    x: box.x + insets.left,
+    y: box.y + insets.top,
+    width: Math.max(0, box.width - insets.left - insets.right),
+    height: Math.max(0, box.height - insets.top - insets.bottom),
+  };
+}
+
+/**
+ * Intersection of two boxes, or `undefined` when they do not overlap. Touching edges count as an
+ * empty (zero-area) intersection and also return `undefined`, except when one of the boxes is
+ * itself degenerate (a zero-size target is "visible" when it lies inside the other box).
+ */
+export function intersect(a: Box, b: Box): Box | undefined {
+  const x1 = Math.max(a.x, b.x);
+  const y1 = Math.max(a.y, b.y);
+  const x2 = Math.min(right(a), right(b));
+  const y2 = Math.min(bottom(a), bottom(b));
+  if (x2 < x1 || y2 < y1) {
+    return undefined;
+  }
+
+  const degenerate = a.width === 0 || a.height === 0 || b.width === 0 || b.height === 0;
+  if (!degenerate && (x2 === x1 || y2 === y1)) {
+    return undefined;
+  }
+
+  return {x: x1, y: y1, width: x2 - x1, height: y2 - y1};
+}
+
+/** Collapses `box` onto the nearest edge of `area` when the two do not overlap (a zero-size box on that edge). */
+export function projectOnto(box: Box, area: Box): Box {
+  const x1 = clamp(box.x, area.x, right(area));
+  const x2 = clamp(right(box), area.x, right(area));
+  const y1 = clamp(box.y, area.y, bottom(area));
+  const y2 = clamp(bottom(box), area.y, bottom(area));
+  return {x: x1, y: y1, width: x2 - x1, height: y2 - y1};
+}
+
+/**
+ * Narrows a clip area by another clipping box. When the two do not overlap, the result is an empty
+ * box on the edge of `box` nearest to `clip`, so it still tells in which direction the content is.
+ */
+export function narrowClip(clip: Box | undefined, box: Box): Box {
+  if (!clip) {
+    return box;
+  }
+
+  return intersect(clip, box) ?? projectOnto(clip, box);
+}
+
+export function containsPoint(box: Box, point: Point): boolean {
+  return point.x >= box.x && point.x <= right(box) && point.y >= box.y && point.y <= bottom(box);
+}
+
+export function containsBox(outer: Box, inner: Box, epsilon = 0): boolean {
+  return (
+    inner.x >= outer.x - epsilon &&
+    inner.y >= outer.y - epsilon &&
+    right(inner) <= right(outer) + epsilon &&
+    bottom(inner) <= bottom(outer) + epsilon
+  );
+}
+
+export function boxesEqual(a: Box | undefined, b: Box | undefined, epsilon = 0.01): boolean {
+  if (a === b) {
+    return true;
+  }
+
+  if (!a || !b) {
+    return false;
+  }
+
+  return (
+    Math.abs(a.x - b.x) <= epsilon &&
+    Math.abs(a.y - b.y) <= epsilon &&
+    Math.abs(a.width - b.width) <= epsilon &&
+    Math.abs(a.height - b.height) <= epsilon
+  );
+}
+
+export function sizesEqual(a: Size | undefined, b: Size | undefined, epsilon = 0.01): boolean {
+  if (a === b) {
+    return true;
+  }
+
+  if (!a || !b) {
+    return false;
+  }
+
+  return Math.abs(a.width - b.width) <= epsilon && Math.abs(a.height - b.height) <= epsilon;
+}
+
+export function insetsEqual(a: Insets, b: Insets, epsilon = 0.01): boolean {
+  return (
+    Math.abs(a.top - b.top) <= epsilon &&
+    Math.abs(a.right - b.right) <= epsilon &&
+    Math.abs(a.bottom - b.bottom) <= epsilon &&
+    Math.abs(a.left - b.left) <= epsilon
+  );
+}
+
+export function pointsEqual(a: Point, b: Point, epsilon = 0.01): boolean {
+  return Math.abs(a.x - b.x) <= epsilon && Math.abs(a.y - b.y) <= epsilon;
+}

package/src/shared/geometry/compute-tooltip-layout.util.ts

@@ -0,0 +1,238 @@
+import {
+  bottom,
+  centerX,
+  centerY,
+  clamp,
+  deflate,
+  finiteOr,
+  inflate,
+  intersect,
+  projectOnto,
+  right,
+  sanitizeBox,
+  sanitizeInsets,
+  sanitizeLength,
+  sanitizeSize,
+} from './box.util.js';
+import type {Box, Side, Size, Viewport} from './geometry.type.js';
+
+export type LayoutPlacement = Side | 'center';
+
+export type TooltipLayoutInput = {
+  /** The target in layer coordinates, or `undefined` for a centred step. */
+  readonly target: Box | undefined;
+  /** The tooltip's measured size (already rendered with `maxWidth`/`maxHeight` applied). */
+  readonly tooltip: Size;
+  readonly viewport: Viewport;
+  /** Preferred side. */
+  readonly placement: Side;
+  /** Side used for the same step before; kept while it still fits so the tooltip does not flip-flop. */
+  readonly previousPlacement?: LayoutPlacement | undefined;
+  /** Distance between the highlighted area and the tooltip. Arrows must not be longer than this. */
+  readonly gap: number;
+  /** Space between the target and the edge of the highlighted area. */
+  readonly highlightPadding: number;
+  /** Minimum distance between the tooltip and the edge of the safe area. */
+  readonly viewportPadding: number;
+  /** Minimum distance between the arrow and the tooltip's corners. */
+  readonly arrowPadding: number;
+  /** When set, the position is snapped to device pixels without leaving the safe area. */
+  readonly pixelRatio?: number;
+};
+
+export type TooltipLayout = {
+  readonly x: number;
+  readonly y: number;
+  /** The size the tooltip occupies; the box `x, y, width, height` always lies inside the safe area. */
+  readonly width: number;
+  readonly height: number;
+  /** Side the tooltip was placed on, or `'center'` for steps without a target. */
+  readonly placement: LayoutPlacement;
+  /** Size limits the tooltip must be rendered with. Independent of the tooltip's size, so measuring again with them is stable. */
+  readonly maxWidth: number;
+  readonly maxHeight: number;
+  /** Offset of the arrow along the tooltip edge facing the target, or `undefined` when no arrow should be drawn. */
+  readonly arrowOffset: number | undefined;
+};
+
+const sides: readonly Side[] = ['top', 'right', 'bottom', 'left'];
+const knownSides = new Set<string>(sides);
+
+/**
+ * Sub-pixel slack when deciding whether a side has room. Without it, floating-point noise (for
+ * example from scrolling) could flip the tooltip between sides for differences of 1e-15 px.
+ */
+export const fitTolerance = 1e-7;
+
+const opposite: Record<Side, Side> = {top: 'bottom', bottom: 'top', left: 'right', right: 'left'};
+
+const perpendicular: Record<Side, readonly [Side, Side]> = {
+  top: ['right', 'left'],
+  bottom: ['right', 'left'],
+  left: ['top', 'bottom'],
+  right: ['top', 'bottom'],
+};
+
+function isVertical(side: Side): boolean {
+  return side === 'top' || side === 'bottom';
+}
+
+/**
+ * The area the tooltip may occupy: the viewport minus obstructed insets minus padding. On an axis
+ * where that would leave less than one pixel, the padding is dropped first and then the insets, so
+ * the result is never empty while the viewport itself has room. The result is always inside the
+ * viewport rect.
+ */
+export function getSafeArea(viewport: Viewport, viewportPadding: number): Box {
+  const rect = sanitizeBox(viewport.rect);
+  const insets = sanitizeInsets(viewport.insets);
+  const padding = sanitizeLength(viewportPadding);
+
+  const axis = (start: number, size: number, insetStart: number, insetEnd: number): [number, number] => {
+    const candidates: Array<[number, number]> = [
+      [start + insetStart + padding, start + size - insetEnd - padding],
+      [start + insetStart, start + size - insetEnd],
+    ];
+    for (const [from, to] of candidates) {
+      if (to - from >= 1) {
+        return [from, to];
+      }
+    }
+
+    return [start, start + size];
+  };
+
+  const [x1, x2] = axis(rect.x, rect.width, insets.left, insets.right);
+  const [y1, y2] = axis(rect.y, rect.height, insets.top, insets.bottom);
+  return {x: x1, y: y1, width: x2 - x1, height: y2 - y1};
+}
+
+/**
+ * Where to put the tooltip so it never leaves the visible, unobstructed part of the screen.
+ *
+ * Guarantees, for any input (including non-finite numbers):
+ * - the returned box lies inside the safe area (see {@link getSafeArea}), and therefore inside the viewport;
+ * - `maxWidth`/`maxHeight` depend only on the viewport, so re-measuring with them reaches a fixed point;
+ * - when any side has room, the tooltip does not overlap the highlighted area;
+ * - the preferred side wins whenever it fits, then the opposite side, then the roomier perpendicular side.
+ */
+export function computeTooltipLayout(input: TooltipLayoutInput): TooltipLayout {
+  const safe = getSafeArea(input.viewport, input.viewportPadding);
+  const gap = sanitizeLength(input.gap);
+  const tooltip = sanitizeSize(input.tooltip);
+  const width = Math.min(tooltip.width, safe.width);
+  const height = Math.min(tooltip.height, safe.height);
+  const base = {width, height, maxWidth: safe.width, maxHeight: safe.height};
+
+  const finish = (x: number, y: number, placement: LayoutPlacement, arrowOffset: number | undefined): TooltipLayout => {
+    const snapped = snap(x, y, input.pixelRatio);
+    return {
+      ...base,
+      x: clamp(snapped.x, safe.x, right(safe) - width),
+      y: clamp(snapped.y, safe.y, bottom(safe) - height),
+      placement,
+      arrowOffset,
+    };
+  };
+
+  const rawTarget = input.target ? sanitizeBox(input.target) : undefined;
+  if (!rawTarget) {
+    return finish(safe.x + (safe.width - width) / 2, safe.y + (safe.height - height) / 2, 'center', undefined);
+  }
+
+  const anchor = inflate(rawTarget, sanitizeLength(input.highlightPadding));
+  const visible = intersect(anchor, safe);
+  const effective = visible ?? projectOnto(anchor, safe);
+
+  const space: Record<Side, number> = {
+    top: effective.y - safe.y - gap,
+    bottom: bottom(safe) - bottom(effective) - gap,
+    left: effective.x - safe.x - gap,
+    right: right(safe) - right(effective) - gap,
+  };
+  const room = (side: Side): number => space[side] - (isVertical(side) ? height : width);
+  const fits = (side: Side): boolean => room(side) >= -fitTolerance;
+
+  const preferred: Side = knownSides.has(input.placement) ? input.placement : 'bottom';
+  const order: Side[] = [preferred, opposite[preferred], ...roomiestFirst(perpendicular[preferred], room)];
+  const previous = input.previousPlacement;
+  if (previous && previous !== 'center' && previous !== preferred) {
+    order.unshift(previous);
+  }
+
+  const chosen = order.find((side) => fits(side));
+  const side = chosen ?? roomiestFirst(order, room)[0] ?? preferred;
+  const position = placeOnSide({side, anchor: effective, size: {width, height}, gap, safe});
+
+  // The arrow points at the centre of the part of the actual target the user can see.
+  const visibleTarget = intersect(
+    rawTarget,
+    deflate(sanitizeBox(input.viewport.rect), sanitizeInsets(input.viewport.insets)),
+  );
+  let arrowOffset: number | undefined;
+  if (chosen && visibleTarget) {
+    const edge = isVertical(side) ? width : height;
+    const inset = Math.min(sanitizeLength(input.arrowPadding), edge / 2);
+    const target = isVertical(side) ? centerX(visibleTarget) - position.x : centerY(visibleTarget) - position.y;
+    arrowOffset = clamp(target, inset, edge - inset);
+  }
+
+  return finish(position.x, position.y, side, arrowOffset);
+}
+
+/**
+ * Sorts sides by available room, largest first. Sides whose room differs by less than
+ * {@link fitTolerance} keep their given order, so the result does not depend on rounding noise.
+ */
+function roomiestFirst(candidates: readonly Side[], room: (side: Side) => number): Side[] {
+  const result: Side[] = [];
+  for (const side of candidates) {
+    const index = result.findIndex((other) => room(side) > room(other) + fitTolerance);
+    if (index === -1) {
+      result.push(side);
+    } else {
+      result.splice(index, 0, side);
+    }
+  }
+
+  return result;
+}
+
+type PlaceOnSideInput = {
+  readonly side: Side;
+  readonly anchor: Box;
+  readonly size: Size;
+  readonly gap: number;
+  readonly safe: Box;
+};
+
+function placeOnSide({side, anchor, size, gap, safe}: PlaceOnSideInput): {x: number; y: number} {
+  const crossX = clamp(centerX(anchor) - size.width / 2, safe.x, right(safe) - size.width);
+  const crossY = clamp(centerY(anchor) - size.height / 2, safe.y, bottom(safe) - size.height);
+  switch (side) {
+    case 'top': {
+      return {x: crossX, y: anchor.y - gap - size.height};
+    }
+
+    case 'bottom': {
+      return {x: crossX, y: bottom(anchor) + gap};
+    }
+
+    case 'left': {
+      return {x: anchor.x - gap - size.width, y: crossY};
+    }
+
+    case 'right': {
+      return {x: right(anchor) + gap, y: crossY};
+    }
+  }
+}
+
+function snap(x: number, y: number, pixelRatio: number | undefined): {x: number; y: number} {
+  const ratio = finiteOr(pixelRatio ?? 0, 0);
+  if (ratio <= 0) {
+    return {x, y};
+  }
+
+  return {x: Math.round(x * ratio) / ratio, y: Math.round(y * ratio) / ratio};
+}

package/src/shared/geometry/geometry.type.ts

@@ -0,0 +1,38 @@
+/**
+ * Axis-aligned box in the tour layer's coordinate space (CSS pixels on web, density-independent
+ * pixels on React Native). `x`/`y` are the top-left corner.
+ */
+export type Box = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+export type Size = {
+  readonly width: number;
+  readonly height: number;
+};
+
+export type Point = {
+  readonly x: number;
+  readonly y: number;
+};
+
+export type Insets = {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+};
+
+/**
+ * The region the user can actually see, plus the parts of it that are obstructed
+ * (notch, home indicator, on-screen keyboard, system bars).
+ */
+export type Viewport = {
+  readonly rect: Box;
+  readonly insets: Insets;
+};
+
+export type Side = 'top' | 'bottom' | 'left' | 'right';

package/src/shared/geometry/reveal.util.ts

@@ -0,0 +1,190 @@
+import {bottom, right, zeroInsets} from './box.util.js';
+import type {Box, Insets, Point, Side, Size} from './geometry.type.js';
+
+const fitSlack = 1e-6;
+
+/**
+ * How far a container has to scroll (positive: further down/right) so that the target plus a
+ * margin is inside `area` and clear of `obstacles` (elements that stay put while the content
+ * scrolls: sticky headers, floating buttons, cookie banners, any number of them).
+ *
+ * Per axis, the obstacles in the target's column (row) cut the area into free gaps. The target is
+ * moved into the gap that needs the least scrolling, so scrolling up and down behave the same. The
+ * first margin that fits is used (preferring one that fits on both axes). A target that only fits
+ * without margin is centred in the nearest gap that can hold it; a target that fits in no gap is
+ * aligned to the start of the largest one, keeping the smallest margin.
+ */
+export function computeRevealDelta(
+  target: Box,
+  area: Box,
+  margins: readonly Insets[],
+  obstacles: readonly Box[] = [],
+): Point {
+  const candidates = margins.length > 0 ? margins : [zeroInsets];
+  const smallest = candidates.at(-1) ?? zeroInsets;
+  // Pages scroll vertically: the vertical gaps depend on the obstacles in the target's column, the
+  // horizontal ones on the obstacles in the row the target ends up in.
+  const ySegments = freeSegments(
+    area.y,
+    bottom(area),
+    obstacles.filter((o) => o.x < right(target) && right(o) > target.x).map((o) => [o.y, bottom(o)] as const),
+  );
+  const xSegmentsAfter = (dy: number): Segment[] =>
+    freeSegments(
+      area.x,
+      right(area),
+      obstacles
+        .filter((o) => o.y < bottom(target) - dy && bottom(o) > target.y - dy)
+        .map((o) => [o.x, right(o)] as const),
+    );
+  const yAxis = {start: target.y, size: target.height};
+  const xAxis = {start: target.x, size: target.width};
+
+  // The first margin that fits on both axes (it may leave room for the tooltip on one side).
+  for (const margin of candidates) {
+    const y = fitDelta(yAxis, ySegments, [margin.top, margin.bottom]);
+    const x = y === undefined ? undefined : fitDelta(xAxis, xSegmentsAfter(y), [margin.left, margin.right]);
+    if (y !== undefined && x !== undefined) {
+      return {x, y};
+    }
+  }
+
+  // Otherwise each axis on its own.
+  const y =
+    firstDefined(candidates, (m) => fitDelta(yAxis, ySegments, [m.top, m.bottom])) ??
+    fallbackDelta(yAxis, ySegments, smallest.top);
+  const xSegments = xSegmentsAfter(y);
+  const x =
+    firstDefined(candidates, (m) => fitDelta(xAxis, xSegments, [m.left, m.right])) ??
+    fallbackDelta(xAxis, xSegments, smallest.left);
+  return {x, y};
+}
+
+function firstDefined<T>(items: readonly T[], map: (item: T) => number | undefined): number | undefined {
+  for (const item of items) {
+    const value = map(item);
+    if (value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+type Segment = {readonly from: number; readonly to: number};
+
+/** The parts of `[from, to]` not covered by `blocked`. Fully blocked: the whole range (nothing can be avoided). */
+export function freeSegments(from: number, to: number, blocked: ReadonlyArray<readonly [number, number]>): Segment[] {
+  const sorted = [...blocked]
+    .map(([a, b]) => [Math.max(a, from), Math.min(b, to)] as const)
+    .filter(([a, b]) => b > a)
+    // eslint-disable-next-line unicorn/no-array-sort -- sorting a fresh copy (ES2023 `toSorted` is not available on every supported React Native version)
+    .sort((a, b) => a[0] - b[0]);
+  const segments: Segment[] = [];
+  let cursor = from;
+  for (const [a, b] of sorted) {
+    if (a > cursor) {
+      segments.push({from: cursor, to: a});
+    }
+
+    cursor = Math.max(cursor, b);
+  }
+
+  if (to > cursor) {
+    segments.push({from: cursor, to});
+  }
+
+  return segments.length > 0 ? segments : [{from, to}];
+}
+
+type Axis = {readonly start: number; readonly size: number};
+
+/** Smallest movement that puts `[from, to]` inside `segment`. */
+function deltaInto(from: number, to: number, segment: Segment): number {
+  if (from < segment.from) {
+    return from - segment.from;
+  }
+
+  return to > segment.to ? to - segment.to : 0;
+}
+
+function smallestBy<T>(items: readonly T[], score: (item: T) => number): T | undefined {
+  let best: T | undefined;
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const item of items) {
+    const value = score(item);
+    if (value < bestScore) {
+      best = item;
+      bestScore = value;
+    }
+  }
+
+  return best;
+}
+
+/** The smallest movement that puts the target plus margin into a gap that can hold it, if any. */
+function fitDelta(
+  {start, size}: Axis,
+  segments: readonly Segment[],
+  [before, after]: readonly [number, number],
+): number | undefined {
+  const from = start - before;
+  const to = start + size + after;
+  // Sub-pixel slack: gap widths computed from coordinates lose their last bits of precision.
+  const fitting = segments.filter((segment) => segment.to - segment.from >= to - from - fitSlack);
+  const best = smallestBy(fitting, (segment) => Math.abs(deltaInto(from, to, segment)));
+  return best ? deltaInto(from, to, best) : undefined;
+}
+
+/**
+ * When no margin fits: centre the target in the nearest gap that can hold it, or align it to the
+ * start of the largest gap (keeping `leadingMargin`) when it fits nowhere.
+ */
+function fallbackDelta({start, size}: Axis, segments: readonly Segment[], leadingMargin: number): number {
+  const centreDelta = (segment: Segment): number => start + size / 2 - (segment.from + segment.to) / 2;
+  const holding = segments.filter((segment) => segment.to - segment.from >= size);
+  const nearest = smallestBy(holding, (segment) => Math.abs(centreDelta(segment)));
+  if (nearest) {
+    return centreDelta(nearest);
+  }
+
+  const largest = smallestBy(segments, (segment) => -(segment.to - segment.from)) ?? {from: start, to: start};
+  return start - Math.min(leadingMargin, (largest.to - largest.from) / 2) - largest.from;
+}
+
+export type RevealMarginInput = {
+  readonly target: Box;
+  readonly tooltip: Size;
+  /** The visible, unobstructed part of the screen. */
+  readonly area: Box;
+  /** Sides in the order the tooltip would try them. */
+  readonly sides: readonly Side[];
+  readonly gap: number;
+  readonly highlightPadding: number;
+  readonly viewportPadding: number;
+};
+
+/**
+ * Margins to keep around the target while scrolling it into view. The first entry also leaves
+ * room for the tooltip on the first side (in the given order) where target and tooltip fit on
+ * screen together. The last entry only keeps the highlight padding and viewport padding.
+ */
+export function buildRevealMargins(input: RevealMarginInput): Insets[] {
+  const base = input.highlightPadding + input.viewportPadding;
+  const baseMargin: Insets = {top: base, right: base, bottom: base, left: base};
+  for (const side of input.sides) {
+    const vertical = side === 'top' || side === 'bottom';
+    const room = input.gap + (vertical ? input.tooltip.height : input.tooltip.width);
+    const mainFits = vertical
+      ? input.target.height + base * 2 + room <= input.area.height
+      : input.target.width + base * 2 + room <= input.area.width;
+    const crossFits = vertical
+      ? input.tooltip.width + input.viewportPadding * 2 <= input.area.width
+      : input.tooltip.height + input.viewportPadding * 2 <= input.area.height;
+    if (mainFits && crossFits) {
+      return [{...baseMargin, [side]: base + room}, baseMargin];
+    }
+  }
+
+  return [baseMargin];
+}

package/src/shared/geometry/target-visibility.util.ts

@@ -0,0 +1,44 @@
+import type {Box} from './geometry.type.js';
+
+/**
+ * How much of a target the user can see:
+ * - `full`: the whole target is visible, or, for targets larger than the area, it covers the area.
+ * - `partial`: at least half of what could be visible is visible on both axes.
+ * - `none`: anything less.
+ */
+export type TargetVisibility = 'full' | 'partial' | 'none';
+
+function axisVisibility(start: number, size: number, areaStart: number, areaSize: number): TargetVisibility {
+  const end = start + size;
+  const areaEnd = areaStart + areaSize;
+  if (areaSize <= 0) {
+    return 'none';
+  }
+
+  if (size === 0) {
+    return start >= areaStart && start <= areaEnd ? 'full' : 'none';
+  }
+
+  const fullyInside = start >= areaStart && end <= areaEnd;
+  const covers = start <= areaStart && end >= areaEnd;
+  if (size <= areaSize ? fullyInside : covers) {
+    return 'full';
+  }
+
+  const visible = Math.max(0, Math.min(end, areaEnd) - Math.max(start, areaStart));
+  if (visible === 0 || visible < Math.min(size, areaSize) / 2) {
+    return 'none';
+  }
+
+  return 'partial';
+}
+
+export function getTargetVisibility(target: Box, area: Box): TargetVisibility {
+  const horizontal = axisVisibility(target.x, target.width, area.x, area.width);
+  const vertical = axisVisibility(target.y, target.height, area.y, area.height);
+  if (horizontal === 'none' || vertical === 'none') {
+    return 'none';
+  }
+
+  return horizontal === 'full' && vertical === 'full' ? 'full' : 'partial';
+}