Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | 31x 31x 31x 7x 31x 31x 31x 14x 7x 31x 31x 7x 7x 2x 2x 2x 31x 14x 7x 7x 7x 7x 5x 5x 31x 31x 31x 7x 1x 6x 1x | import * as React from "react";
import { useEffect, useRef, useState } from "react";
import { createPortal } from "react-dom";
import { clsx } from "clsx";
import { useLatest } from "@usefy/use-latest";
import { useMutationObserver } from "@usefy/use-mutation-observer";
import { useReducedMotion } from "@usefy/use-reduced-motion";
import { resolveTarget } from "../../engine/resolveTarget";
import { useTargetRect } from "../../hooks/useTargetRect";
import { MUTATION_RERESOLVE_THROTTLE_MS } from "../../useSpotlightTour";
import type { TourTarget } from "../../types";
import styles from "./Beacon.module.scss";
/** Props for {@link SpotlightBeacon}. */
export interface SpotlightBeaconProps {
/** Element the beacon attaches to (selector / ref / function). */
target: TourTarget;
/** Called on click — typically `() => controller.current?.start(2)`. */
onActivate: () => void;
/** Accessible name of the beacon button. @default "Start tour" */
"aria-label"?: string;
/** Extra class on the beacon button. */
className?: string;
}
/**
* A pulsing invitation dot pinned to an element's top-right corner — the
* classic "psst, there's a tour here" affordance. A real `<button>` (portal
* into `document.body`), so it is keyboard-focusable and screen-reader
* announceable (`aria-label`, default "Start tour").
*
* Behavior:
* - Tracks the target's live position via the same rAF-batched rect tracking
* the tour uses (scroll/resize/element resize).
* - Renders **nothing** while the target is unresolved, and re-resolves on
* DOM mutation (throttled) — it appears when a late target mounts and
* disappears if the target unmounts.
* - The pulse is pure CSS; under reduced motion it renders a static halo.
* - SSR-safe: portals only after mount.
*
* Styled-entry export only (`@usefy/spotlight-tour`) — headless consumers can
* build their own from `useTargetRect` + `resolveTarget`.
*
* @example
* ```tsx
* import { useRef } from "react";
* import { SpotlightTour, SpotlightBeacon, type TourController } from "@usefy/spotlight-tour";
*
* function App() {
* const controller = useRef<TourController>(null);
* return (
* <>
* <SpotlightBeacon target="#search" onActivate={() => controller.current?.start()} />
* <SpotlightTour controllerRef={controller} steps={[{ target: "#search", content: "Search!" }]} />
* </>
* );
* }
* ```
*/
export function SpotlightBeacon(props: SpotlightBeaconProps): React.ReactNode {
const {
target,
onActivate,
"aria-label": ariaLabel = "Start tour",
className,
} = props;
// Portal only after mount (SSR-safe).
const [mounted, setMounted] = useState(false);
useEffect(() => {
setMounted(true);
}, []);
const targetRef = useLatest(target);
const [element, setElement] = useState<Element | null>(null);
// Initial resolution (and on target prop change). `setElement` bails on
// identical values, so an inline function/ref target never loops.
useEffect(() => {
if (!mounted) return;
setElement(resolveTarget(targetRef.current));
}, [mounted, target, targetRef]);
// Re-resolve on DOM mutation (throttled): a late-mounting target makes the
// beacon appear; an unmounting one clears it (resolveTarget treats
// disconnected nodes as unresolved).
const throttleRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const { observe, disconnect } = useMutationObserver({
childList: true,
subtree: true,
updateState: false,
enabled: mounted,
onMutation: () => {
Iif (throttleRef.current !== null) return;
throttleRef.current = setTimeout(() => {
throttleRef.current = null;
const next = resolveTarget(targetRef.current);
setElement((prev) => (prev === next ? prev : next));
}, MUTATION_RERESOLVE_THROTTLE_MS);
},
});
useEffect(() => {
if (!mounted || typeof document === "undefined") return;
observe(document.body);
return () => {
disconnect();
if (throttleRef.current !== null) {
clearTimeout(throttleRef.current);
throttleRef.current = null;
}
};
}, [mounted, observe, disconnect]);
const rect = useTargetRect(element);
const reducedMotion = useReducedMotion();
if (!mounted || !rect) return null;
// An all-zero rect means the target isn't really visible (display:none, or
// a detached-node measurement) — don't pin a beacon to the viewport origin.
if (rect.x === 0 && rect.y === 0 && rect.width === 0 && rect.height === 0) {
return null;
}
return createPortal(
<button
type="button"
className={clsx(styles.beacon, reducedMotion && styles.static, className)}
// Centered on the target's top-right corner, tracking live.
style={{ left: rect.x + rect.width, top: rect.y }}
aria-label={ariaLabel}
onClick={onActivate}
data-tour-beacon=""
/>,
document.body
);
}
SpotlightBeacon.displayName = "SpotlightBeacon";
|