@gogitcms/design-system 0.15.0-next.3

package/src/components/Onboarding.tsx

@@ -0,0 +1,751 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { Pressable, View, useWindowDimensions } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+import { Button, IconButton } from "./Button";
+
+/**
+ * The guided-tour framework: a spotlight overlay that walks someone through a
+ * screen one anchored step at a time.
+ *
+ * Three pieces, deliberately separable:
+ *
+ *  - `useOnboardingTarget(id)` marks a piece of UI as anchorable. It hands back
+ *    a ref and nothing else, so anchoring a step to an existing element never
+ *    changes that element's layout — the failure mode of every tour library
+ *    that asks you to wrap things.
+ *  - `OnboardingProvider` owns which flow is running and where in it we are,
+ *    and renders the overlay.
+ *  - `useOnboarding()` is the host's handle: start a tour, replay one, ask
+ *    whether one has been seen.
+ *
+ * Persistence is a seam, not a dependency: the provider takes `progress` and
+ * calls `onProgress`, so the dashboard can back it with REST and the editor SPA
+ * with GraphQL without this file knowing either exists.
+ */
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Where a step's card sits relative to its target. */
+export type OnboardingPlacement = "auto" | "top" | "bottom" | "left" | "right" | "center";
+
+export type OnboardingFlowStep = {
+  id: string;
+  title: string;
+  body: string;
+  /**
+   * The id passed to `useOnboardingTarget`. Absent — or present but not
+   * currently rendered — falls back to a centered card, which is what makes a
+   * step that describes the screen as a whole (or one whose target is hidden on
+   * mobile) degrade rather than break.
+   */
+  target?: string;
+  placement?: OnboardingPlacement;
+  /**
+   * Run when the step becomes current. For steps whose target only exists once
+   * something is open — a menu, a drawer — the host opens it here.
+   */
+  onEnter?: () => void;
+};
+
+export type OnboardingFlow = {
+  id: string;
+  /**
+   * Bumped when the tour's content changes materially. A user whose recorded
+   * version is lower is offered the tour again; this is why completion is not
+   * stored as a bare boolean.
+   */
+  version: number;
+  /** Shown as the overlay's kicker, e.g. "Dashboard tour". */
+  title: string;
+  steps: OnboardingFlowStep[];
+};
+
+export type OnboardingStatus = "pending" | "in_progress" | "completed" | "skipped";
+
+/** One flow's recorded position. Mirrors the server's row. */
+export type OnboardingProgress = {
+  status: OnboardingStatus;
+  stepIndex: number;
+  version: number;
+};
+
+export type OnboardingSession = {
+  flow: OnboardingFlow;
+  step: OnboardingFlowStep;
+  index: number;
+  total: number;
+};
+
+export type OnboardingApi = {
+  /** The running tour, or null. */
+  session: OnboardingSession | null;
+  /** Start (or resume) a flow. `atIndex` overrides the resume point. */
+  start: (flowId: string, atIndex?: number) => void;
+  /** Run a flow from the top regardless of what has been recorded. */
+  restart: (flowId: string) => void;
+  next: () => void;
+  back: () => void;
+  /** Dismiss: records `skipped`. */
+  skip: () => void;
+  /** Close without recording anything (route changes, unmount). */
+  stop: () => void;
+  /** What has been recorded for a flow — `pending` when nothing has. */
+  statusFor: (flowId: string) => OnboardingStatus;
+  /** True when the flow is worth offering, i.e. never seen or its version bumped. */
+  isUnseen: (flowId: string) => boolean;
+  flows: OnboardingFlow[];
+};
+
+type Rect = { x: number; y: number; width: number; height: number };
+
+// ── Target registry ────────────────────────────────────────────────────────
+
+type Registry = {
+  register: (id: string, node: unknown) => void;
+  unregister: (id: string) => void;
+  get: (id: string) => unknown;
+  /** Fires when a target mounts or unmounts, so a waiting step can re-measure. */
+  subscribe: (fn: () => void) => () => void;
+};
+
+const TargetsCtx = createContext<Registry | null>(null);
+const OnboardingCtx = createContext<OnboardingApi | null>(null);
+
+function createRegistry(): Registry {
+  const nodes = new Map<string, unknown>();
+  const subs = new Set<() => void>();
+  const notify = () => subs.forEach((fn) => fn());
+  return {
+    register(id, node) {
+      nodes.set(id, node);
+      notify();
+    },
+    unregister(id) {
+      nodes.delete(id);
+      notify();
+    },
+    get: (id) => nodes.get(id),
+    subscribe(fn) {
+      subs.add(fn);
+      return () => subs.delete(fn);
+    },
+  };
+}
+
+/**
+ * Marks a piece of UI as a tour anchor. Spread the returned ref onto any View:
+ *
+ *   const stats = useOnboardingTarget("dash.stats");
+ *   <View ref={stats.ref} style={…}>
+ *
+ * Registering is layout-neutral by construction — no wrapper element, no style.
+ */
+export function useOnboardingTarget(id: string): { ref: (node: unknown) => void } {
+  const reg = useContext(TargetsCtx);
+  const ref = useCallback(
+    (node: unknown) => {
+      if (!reg) return;
+      if (node) reg.register(id, node);
+      else reg.unregister(id);
+    },
+    [id, reg],
+  );
+  return { ref };
+}
+
+/** Wrapper form of `useOnboardingTarget`, for anchoring something you don't own. */
+export function OnboardingTarget({
+  id,
+  children,
+  style,
+}: {
+  id: string;
+  children: React.ReactNode;
+  style?: any;
+}) {
+  const { ref } = useOnboardingTarget(id);
+  return (
+    <View ref={ref as any} style={style} collapsable={false}>
+      {children}
+    </View>
+  );
+}
+
+// ── Measurement ────────────────────────────────────────────────────────────
+
+// measureNode reads a node's viewport rect. On react-native-web the ref is the
+// DOM element, so getBoundingClientRect is both available and cheaper than RN's
+// callback API; measureInWindow is the native path. A zero-sized result counts
+// as "not measurable" — that is what a display:none target looks like.
+function measureNode(node: any): Promise<Rect | null> {
+  return new Promise((resolve) => {
+    if (!node) {
+      resolve(null);
+      return;
+    }
+    if (typeof node.getBoundingClientRect === "function") {
+      const r = node.getBoundingClientRect();
+      resolve(r.width || r.height ? { x: r.left, y: r.top, width: r.width, height: r.height } : null);
+      return;
+    }
+    if (typeof node.measureInWindow === "function") {
+      node.measureInWindow((x: number, y: number, width: number, height: number) => {
+        resolve(width || height ? { x, y, width, height } : null);
+      });
+      return;
+    }
+    resolve(null);
+  });
+}
+
+// scrollIntoViewIfNeeded brings an off-screen anchor into view before the
+// spotlight is drawn around it. Web-only and best-effort: a tour that silently
+// highlights something below the fold is worse than one that scrolls.
+function scrollIntoViewIfNeeded(node: any, rect: Rect | null, viewportH: number) {
+  if (!node || typeof node.scrollIntoView !== "function" || !rect) return false;
+  if (rect.y >= 0 && rect.y + rect.height <= viewportH) return false;
+  try {
+    node.scrollIntoView({ block: "center", inline: "nearest", behavior: "smooth" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Tracks a target's rect while a step is showing.
+ *
+ * Measuring once is not enough: the anchor may not have mounted yet (data still
+ * loading), the page may need scrolling to reach it, and the window may resize
+ * under the overlay. So this re-measures on a short poll that stops as soon as
+ * the rect settles, and on every resize, scroll and registry change.
+ */
+function useTargetRect(targetId: string | undefined, stepKey: string): Rect | null {
+  const reg = useContext(TargetsCtx);
+  const { height: viewportH } = useWindowDimensions();
+  const [rect, setRect] = useState<Rect | null>(null);
+  const last = useRef<Rect | null>(null);
+  const scrolled = useRef(false);
+
+  useEffect(() => {
+    if (!targetId || !reg) {
+      last.current = null;
+      setRect(null);
+      return;
+    }
+    let cancelled = false;
+    let timer: any;
+    let settled = 0;
+    scrolled.current = false;
+    last.current = null;
+
+    const tick = async () => {
+      if (cancelled) return;
+      const node = reg.get(targetId);
+      const next = await measureNode(node);
+      if (cancelled) return;
+      if (next && !scrolled.current) {
+        scrolled.current = true;
+        // A scroll moves the rect; the poll below picks up the new one.
+        scrollIntoViewIfNeeded(node, next, viewportH);
+      }
+      settled = next && sameRect(last.current, next) ? settled + 1 : 0;
+      if (!sameRect(last.current, next)) {
+        last.current = next;
+        setRect(next);
+      }
+      // Back off once the rect has held still for a few frames, so a settled
+      // tour is not re-measuring the DOM twelve times a second.
+      timer = setTimeout(tick, settled > 3 ? 500 : 80);
+    };
+    tick();
+
+    const unsub = reg.subscribe(() => {
+      clearTimeout(timer);
+      settled = 0;
+      tick();
+    });
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+      unsub();
+    };
+  }, [targetId, stepKey, reg, viewportH]);
+
+  return rect;
+}
+
+function sameRect(a: Rect | null, b: Rect | null): boolean {
+  if (!a || !b) return a === b;
+  return (
+    Math.abs(a.x - b.x) < 0.5 &&
+    Math.abs(a.y - b.y) < 0.5 &&
+    Math.abs(a.width - b.width) < 0.5 &&
+    Math.abs(a.height - b.height) < 0.5
+  );
+}
+
+// ── Provider ───────────────────────────────────────────────────────────────
+
+export type OnboardingProviderProps = {
+  flows: OnboardingFlow[];
+  /**
+   * The flow this screen is about. Changing it ends any running tour — a tour
+   * anchored to a screen you have navigated away from has nothing to point at.
+   */
+  activeFlow?: string;
+  /**
+   * Recorded progress, keyed by flow id. `undefined` means "not loaded yet" and
+   * suppresses auto-start, so a slow round-trip never replays a finished tour.
+   */
+  progress?: Record<string, OnboardingProgress>;
+  /** Persist a position. Called on every step, on skip and on completion. */
+  onProgress?: (flowId: string, next: OnboardingProgress) => void;
+  /**
+   * Hold auto-start until the screen's data has landed. Anchors that render
+   * after their step would otherwise spotlight nothing.
+   */
+  ready?: boolean;
+  /** False turns the whole thing off (embedded surfaces, tests). */
+  enabled?: boolean;
+  children: React.ReactNode;
+  style?: any;
+};
+
+export function OnboardingProvider({
+  flows,
+  activeFlow,
+  progress,
+  onProgress,
+  ready = true,
+  enabled = true,
+  children,
+  style,
+}: OnboardingProviderProps) {
+  const registry = useMemo(createRegistry, []);
+  const [session, setSession] = useState<{ flowId: string; index: number } | null>(null);
+  // Optimistic overlay on `progress`: the host round-trips a write, and until it
+  // comes back the local record is what stops an auto-start loop.
+  const [local, setLocal] = useState<Record<string, OnboardingProgress>>({});
+
+  const merged = useMemo(() => ({ ...(progress ?? {}), ...local }), [progress, local]);
+  const flowById = useCallback((id: string) => flows.find((f) => f.id === id), [flows]);
+
+  const record = useCallback(
+    (flowId: string, next: OnboardingProgress) => {
+      setLocal((prev) => ({ ...prev, [flowId]: next }));
+      onProgress?.(flowId, next);
+    },
+    [onProgress],
+  );
+
+  const statusFor = useCallback(
+    (flowId: string): OnboardingStatus => merged[flowId]?.status ?? "pending",
+    [merged],
+  );
+
+  const isUnseen = useCallback(
+    (flowId: string) => {
+      const flow = flowById(flowId);
+      const p = merged[flowId];
+      if (!flow) return false;
+      if (!p || p.status === "pending") return true;
+      // A bumped version re-offers the tour to someone who finished the old one.
+      return p.version < flow.version;
+    },
+    [flowById, merged],
+  );
+
+  const start = useCallback(
+    (flowId: string, atIndex?: number) => {
+      const flow = flowById(flowId);
+      if (!flow || flow.steps.length === 0) return;
+      const stored = merged[flowId];
+      const resume =
+        atIndex ??
+        (stored && stored.status === "in_progress" && stored.version === flow.version
+          ? stored.stepIndex
+          : 0);
+      const index = Math.min(Math.max(resume, 0), flow.steps.length - 1);
+      setSession({ flowId, index });
+      record(flowId, { status: "in_progress", stepIndex: index, version: flow.version });
+    },
+    [flowById, merged, record],
+  );
+
+  const restart = useCallback((flowId: string) => start(flowId, 0), [start]);
+
+  const stop = useCallback(() => setSession(null), []);
+
+  const next = useCallback(() => {
+    setSession((cur) => {
+      if (!cur) return cur;
+      const flow = flowById(cur.flowId);
+      if (!flow) return null;
+      const last = flow.steps.length - 1;
+      if (cur.index >= last) {
+        record(cur.flowId, { status: "completed", stepIndex: last, version: flow.version });
+        return null;
+      }
+      const index = cur.index + 1;
+      record(cur.flowId, { status: "in_progress", stepIndex: index, version: flow.version });
+      return { ...cur, index };
+    });
+  }, [flowById, record]);
+
+  const back = useCallback(() => {
+    setSession((cur) => {
+      if (!cur || cur.index === 0) return cur;
+      const flow = flowById(cur.flowId);
+      if (!flow) return null;
+      const index = cur.index - 1;
+      record(cur.flowId, { status: "in_progress", stepIndex: index, version: flow.version });
+      return { ...cur, index };
+    });
+  }, [flowById, record]);
+
+  const skip = useCallback(() => {
+    setSession((cur) => {
+      if (!cur) return cur;
+      const flow = flowById(cur.flowId);
+      if (flow) {
+        record(cur.flowId, { status: "skipped", stepIndex: cur.index, version: flow.version });
+      }
+      return null;
+    });
+  }, [flowById, record]);
+
+  // Auto-start: the screen declares which flow it is about, and a flow nobody
+  // has seen (or whose version moved on) runs itself. An in-progress flow
+  // resumes where it stopped rather than restarting.
+  const activeRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (activeRef.current !== activeFlow) {
+      activeRef.current = activeFlow;
+      // Leaving a screen ends its tour; nothing is recorded, so it resumes on
+      // the way back.
+      setSession(null);
+    }
+  }, [activeFlow]);
+
+  useEffect(() => {
+    if (!enabled || !ready || !activeFlow || progress === undefined || session) return;
+    const flow = flowById(activeFlow);
+    if (!flow) return;
+    const p = merged[activeFlow];
+    if (p && (p.status === "completed" || p.status === "skipped") && p.version >= flow.version) return;
+    start(activeFlow);
+  }, [enabled, ready, activeFlow, progress, session, merged, flowById, start]);
+
+  const currentFlow = session ? flowById(session.flowId) : undefined;
+  const api: OnboardingApi = useMemo(
+    () => ({
+      session:
+        currentFlow && session
+          ? {
+              flow: currentFlow,
+              step: currentFlow.steps[session.index],
+              index: session.index,
+              total: currentFlow.steps.length,
+            }
+          : null,
+      start,
+      restart,
+      next,
+      back,
+      skip,
+      stop,
+      statusFor,
+      isUnseen,
+      flows,
+    }),
+    [currentFlow, session, start, restart, next, back, skip, stop, statusFor, isUnseen, flows],
+  );
+
+  return (
+    <TargetsCtx.Provider value={registry}>
+      <OnboardingCtx.Provider value={api}>
+        <View style={[{ flex: 1 }, style]}>
+          {children}
+          {enabled && api.session ? <OnboardingOverlay /> : null}
+        </View>
+      </OnboardingCtx.Provider>
+    </TargetsCtx.Provider>
+  );
+}
+
+/** The host's handle on the running tour. Throws outside a provider. */
+export function useOnboarding(): OnboardingApi {
+  const ctx = useContext(OnboardingCtx);
+  if (!ctx) throw new Error("useOnboarding outside OnboardingProvider");
+  return ctx;
+}
+
+/** Non-throwing form, for shared components that may render without a provider. */
+export function useOnboardingOptional(): OnboardingApi | null {
+  return useContext(OnboardingCtx);
+}
+
+// ── Overlay ────────────────────────────────────────────────────────────────
+
+const CARD_WIDTH = 340;
+const CARD_GAP = 12;
+const HOLE_PAD = 6;
+const EDGE = 16;
+
+// The scrim and the ring are fixed light-on-dark rather than themed: the
+// spotlight always sits on a dark wash, so a themed ring would vanish into it
+// in one mode. Same reasoning as the permanently dark top bar.
+const SCRIM = "rgba(10,10,10,0.55)";
+const RING = "rgba(255,255,255,0.92)";
+
+export function OnboardingOverlay() {
+  const t = useTheme();
+  const { width: vw, height: vh } = useWindowDimensions();
+  const { session, next, back, skip } = useOnboarding();
+  const [cardSize, setCardSize] = useState<{ w: number; h: number } | null>(null);
+
+  const step = session?.step;
+  const stepKey = session ? `${session.flow.id}:${session.index}` : "";
+  const rect = useTargetRect(step?.target, stepKey);
+
+  // Steps that open something (a menu, a drawer) do it here, on entry.
+  const onEnter = step?.onEnter;
+  useEffect(() => {
+    onEnter?.();
+  }, [stepKey, onEnter]);
+
+  // Keyboard: the tour is a modal thing, so it takes the keys a modal takes.
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const onKey = (e: any) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        skip();
+      } else if (e.key === "ArrowRight" || e.key === "Enter") {
+        e.preventDefault();
+        next();
+      } else if (e.key === "ArrowLeft") {
+        e.preventDefault();
+        back();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [next, back, skip]);
+
+  if (!session || !step) return null;
+
+  const hole = rect
+    ? {
+        left: Math.max(rect.x - HOLE_PAD, 0),
+        top: Math.max(rect.y - HOLE_PAD, 0),
+        width: Math.min(rect.width + HOLE_PAD * 2, vw),
+        height: Math.min(rect.height + HOLE_PAD * 2, vh),
+      }
+    : null;
+
+  const cardW = Math.min(CARD_WIDTH, vw - EDGE * 2);
+  const card = placeCard(hole, cardSize, { vw, vh, cardW, placement: step.placement ?? "auto" });
+  const isLast = session.index === session.total - 1;
+
+  return (
+    <View
+      testID="onboarding-overlay"
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        zIndex: 100,
+        // The container spans the viewport, so leaving it hit-testable would
+        // swallow the click on the very control the step points at — the
+        // spotlight would be a picture of an interactive element rather than
+        // the element. It stays transparent to clicks and the pieces that do
+        // need them (the scrim panels, the card) opt back in individually.
+        // Written per-child rather than as `box-none` on the parent because
+        // react-native-web only honours "none"/"auto" from a style object.
+        pointerEvents: "none",
+      }}
+    >
+      {/* The scrim is four rects rather than one with a cut-out: it dims
+          everything but the anchor, and because nothing covers the anchor it
+          stays genuinely clickable — the user can do the thing being described
+          without leaving the tour. */}
+      {hole ? (
+        <>
+          <Backdrop style={{ left: 0, right: 0, top: 0, height: hole.top }} />
+          <Backdrop style={{ left: 0, right: 0, top: hole.top + hole.height, bottom: 0 }} />
+          <Backdrop style={{ left: 0, width: hole.left, top: hole.top, height: hole.height }} />
+          <Backdrop
+            style={{ left: hole.left + hole.width, right: 0, top: hole.top, height: hole.height }}
+          />
+          <View
+            testID="onboarding-spotlight"
+            style={{
+              position: "absolute",
+              // In style rather than as a prop: the ring is decoration, and the
+              // anchor beneath it has to stay clickable through it.
+              pointerEvents: "none",
+              left: hole.left,
+              top: hole.top,
+              width: hole.width,
+              height: hole.height,
+              borderWidth: 2,
+              borderColor: RING,
+              borderRadius: t.radius.md,
+            }}
+          />
+        </>
+      ) : (
+        <Backdrop style={{ left: 0, right: 0, top: 0, bottom: 0 }} />
+      )}
+
+      <View
+        testID="onboarding-card"
+        onLayout={(e) =>
+          setCardSize({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height })
+        }
+        style={{
+          position: "absolute",
+          left: card.left,
+          top: card.top,
+          width: cardW,
+          pointerEvents: "auto",
+          // Held invisible for the first frame only: placement needs the card's
+          // measured height, and a card that jumps is worse than one that fades.
+          opacity: cardSize ? 1 : 0,
+          gap: t.space(3),
+          padding: t.space(4),
+          borderRadius: t.radius.lg,
+          borderWidth: 1,
+          borderColor: t.color.borderDefault,
+          backgroundColor: t.color.surfaceRaised,
+          boxShadow: "0 12px 32px rgba(10,10,10,0.28)",
+        }}
+      >
+        <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+          <Text variant="label" color="tertiary" style={{ flex: 1 }}>
+            {`${session.flow.title} · ${session.index + 1}/${session.total}`}
+          </Text>
+          <IconButton name="x" size="sm" label="Close tour" onPress={skip} testID="onboarding-close" />
+        </View>
+
+        <View style={{ gap: t.space(1.5) }}>
+          <Text variant="h3" weight="semibold">
+            {step.title}
+          </Text>
+          <Text color="secondary">{step.body}</Text>
+        </View>
+
+        <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>
+          <Dots total={session.total} index={session.index} />
+          <View style={{ flex: 1 }} />
+          {session.index > 0 ? (
+            <Button title="Back" size="sm" onPress={back} testID="onboarding-back" />
+          ) : (
+            <Button title="Skip" variant="ghost" size="sm" onPress={skip} testID="onboarding-skip" />
+          )}
+          <Button
+            title={isLast ? "Done" : "Next"}
+            variant="primary"
+            size="sm"
+            onPress={next}
+            testID="onboarding-next"
+          />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+// Backdrop swallows presses so a click meant for the tour never lands on the
+// dimmed UI behind it. It deliberately does not dismiss: losing your place by
+// clicking slightly wide of the card is not a thing a tour should do.
+function Backdrop({ style }: { style: any }) {
+  return (
+    <Pressable
+      onPress={() => {}}
+      style={{ position: "absolute", backgroundColor: SCRIM, pointerEvents: "auto", ...style }}
+    />
+  );
+}
+
+function Dots({ total, index }: { total: number; index: number }) {
+  const t = useTheme();
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(1) }}>
+      {Array.from({ length: total }).map((_, i) => (
+        <View
+          key={i}
+          style={{
+            width: i === index ? 14 : 5,
+            height: 5,
+            borderRadius: t.radius.pill,
+            backgroundColor: i === index ? t.color.textPrimary : t.color.borderDefault,
+          }}
+        />
+      ))}
+    </View>
+  );
+}
+
+type Hole = { left: number; top: number; width: number; height: number };
+
+/**
+ * Places the card beside the spotlight, preferring below, then above, then to
+ * the side, and finally centered. Exported for the tests, which are the only
+ * practical way to check the fallbacks — three of the four need a viewport too
+ * small to reach by hand.
+ */
+export function placeCard(
+  hole: Hole | null,
+  cardSize: { w: number; h: number } | null,
+  view: { vw: number; vh: number; cardW: number; placement: OnboardingPlacement },
+): { left: number; top: number } {
+  const { vw, vh, cardW, placement } = view;
+  const h = cardSize?.h ?? 180;
+
+  if (!hole || placement === "center") {
+    return { left: Math.max((vw - cardW) / 2, EDGE), top: Math.max((vh - h) / 2, EDGE) };
+  }
+
+  const clampX = (x: number) => Math.min(Math.max(x, EDGE), Math.max(vw - cardW - EDGE, EDGE));
+  const clampY = (y: number) => Math.min(Math.max(y, EDGE), Math.max(vh - h - EDGE, EDGE));
+
+  const below = hole.top + hole.height + CARD_GAP;
+  const above = hole.top - CARD_GAP - h;
+  const rightOf = hole.left + hole.width + CARD_GAP;
+  const leftOf = hole.left - CARD_GAP - cardW;
+
+  const fitsBelow = below + h <= vh - EDGE;
+  const fitsAbove = above >= EDGE;
+  const fitsRight = rightOf + cardW <= vw - EDGE;
+  const fitsLeft = leftOf >= EDGE;
+
+  // An explicit placement is honoured when it fits; when it doesn't, falling
+  // back beats rendering the card off-screen.
+  if (placement === "bottom" && fitsBelow) return { left: clampX(centerX(hole, cardW)), top: below };
+  if (placement === "top" && fitsAbove) return { left: clampX(centerX(hole, cardW)), top: above };
+  if (placement === "right" && fitsRight) return { left: rightOf, top: clampY(centerY(hole, h)) };
+  if (placement === "left" && fitsLeft) return { left: leftOf, top: clampY(centerY(hole, h)) };
+
+  if (fitsBelow) return { left: clampX(centerX(hole, cardW)), top: below };
+  if (fitsAbove) return { left: clampX(centerX(hole, cardW)), top: above };
+  if (fitsRight) return { left: rightOf, top: clampY(centerY(hole, h)) };
+  if (fitsLeft) return { left: leftOf, top: clampY(centerY(hole, h)) };
+  return { left: Math.max((vw - cardW) / 2, EDGE), top: Math.max((vh - h) / 2, EDGE) };
+}
+
+const centerX = (hole: Hole, cardW: number) => hole.left + hole.width / 2 - cardW / 2;
+const centerY = (hole: Hole, h: number) => hole.top + hole.height / 2 - h / 2;