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 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 | 301x 301x 301x 301x 301x 301x 301x 301x 301x 25x 25x 301x 104x 23x 2x 23x 301x 267x 301x 301x 301x 301x 301x 13x 288x 575x 2x | import * as React from "react";
import { useEffect, useRef, useState } from "react";
import { clsx } from "clsx";
import { Arrow } from "../Arrow/Arrow";
import type {
RenderStepContext,
SpotlightGeometry,
SpotlightTourClassNames,
TourController,
TourLabels,
TourStep,
} from "../../types";
import styles from "./Tooltip.module.scss";
/** A resolved (non-null) tooltip position from the engine. */
type TooltipPosition = NonNullable<SpotlightGeometry["tooltip"]>;
/** Props for the internal {@link Tooltip}. */
export interface TooltipProps {
/** The active step. */
step: TourStep;
/** Active step index. */
index: number;
/** Total step count. */
count: number;
/** Engine-resolved position, or `null` (unmeasured / centered). */
position: SpotlightGeometry["tooltip"];
/**
* Effective transition duration (ms) — the same value driving the spotlight
* morph and the tooltip's CSS `left`/`top` transition. Used to hold the
* step-move glide "armed" for exactly its duration before returning to the
* snap-on-tracking mode. `0` (reduced motion / disabled) makes every move
* instant.
*/
transitionDuration: number;
/** Render centered (modal mode) instead of positioned. */
centered: boolean;
/** Whether the step's advance gate is unmet (disables Next/Done + hint). */
gated: boolean;
isFirst: boolean;
isLast: boolean;
/** Fully-merged button labels. */
labels: TourLabels;
showProgress: boolean;
showCounter: boolean;
showSkip: boolean;
showClose: boolean;
/** Imperative controls driving the buttons. */
controller: TourController;
/** Props (incl. measurement ref) from `getTooltipProps()`. */
tooltipProps: React.HTMLAttributes<HTMLElement> & {
ref: React.Ref<HTMLElement>;
};
classNames?: SpotlightTourClassNames;
/** Full custom render replacing the default UI (SPEC §4.4). */
renderStep?: (ctx: RenderStepContext) => React.ReactNode;
}
/**
* The step tooltip. A positioning wrapper (absolute at the engine-computed
* position, or CSS-centered for target-less steps, `visibility: hidden` until
* measured) hosts either the default UI — header (title + close), content,
* footer (counter, dots, Back / Skip / Next-Done) — or the consumer's
* `renderStep` output.
*
* With `renderStep`, the wrapper stays visually bare: it only positions and
* carries the measurement ref, while the a11y props are handed to the consumer
* via `ctx.tooltipProps` to spread on their own element.
*
* @internal Rendered by `SpotlightTour`; not part of the public API.
*/
export function Tooltip(props: TooltipProps): React.ReactNode {
const {
step,
index,
count,
position,
transitionDuration,
centered,
gated,
isFirst,
isLast,
labels,
showProgress,
showCounter,
showSkip,
showClose,
controller,
tooltipProps,
classNames,
renderStep,
} = props;
const { ref, ...restTooltipProps } = tooltipProps;
// The hook mints the dialog's labelling ids; stamp them on the elements we
// render so aria-labelledby/-describedby actually resolve.
const titleId = restTooltipProps["aria-labelledby"];
const contentId = restTooltipProps["aria-describedby"];
// --- motion: glide on step change, snap on live tracking ------------------
// The engine feeds `position` as: real coords while the step is settled and
// tracking, then momentarily `null` for the re-measure window on a step
// change (the size hook drops its measurement so the NEW content is measured
// before paint), then the new step's coords — which themselves settle across
// SEVERAL pre-paint commits (element → target rect → size → position all
// cascade). Two things fall out of that and drive the design:
//
// 1. Retention — the last painted coordinates are kept as the effective
// position through the null window, so the box never blanks/hides and
// never teleports; those coords are the CSS transition's from-state.
// 2. Arming — whether to animate CANNOT be decided from an effect: React
// flushes passive effects between the cascade's commits (verified in
// Chrome, not just jsdom), so any effect-updated "last step" marker
// advances mid-cascade and the final positioned commit snaps. Instead we
// arm synchronously (render-phase) when the step index changes and hold
// it armed for the whole synchronous cascade AND the glide's duration
// (disarming any earlier would toggle `transition: none` mid-flight and
// cancel it). Live tracking updates land later, disarmed, and snap 1:1
// (no rubber-band).
//
// • Step-to-step move (target → target) → glide (armed).
// • Live tracking (scroll / resize / auto-scroll) → snap (disarmed).
// • First paint & centered↔targeted → snap (no positioned from-state).
//
// Concurrent-safe: `paintedRef` (retention only) is read in render and
// written in a passive effect; the arm decision is the documented
// setState-during-render derivation — no render-phase ref mutation.
const paintedRef = useRef<TooltipPosition | null>(null);
// Effective coordinates: the live position, or — through the re-measure
// window — the last painted coordinates (retained, never cleared on a step
// change), so the transition's from-state survives.
const activePos = centered ? null : position ?? paintedRef.current;
// Arm a glide the moment the step index changes, but only when there is a
// positioned from-state to move from (target → target). `armed` stays true
// across the settling cascade and is dropped on the next frame below.
const [seenIndex, setSeenIndex] = useState(index);
const [armed, setArmed] = useState(false);
if (seenIndex !== index) {
setSeenIndex(index);
setArmed(!centered && paintedRef.current !== null);
}
useEffect(() => {
if (!armed || typeof window === "undefined") return;
// Hold armed for the glide's full duration, then return to snap mode so
// live tracking sticks 1:1. Disarming any earlier (e.g. next frame) would
// toggle `transition: none` mid-flight and cancel the glide. A small buffer
// guards the transition-end boundary. `seenIndex` is a dep so back-to-back
// step moves each reschedule their own disarm — without it, a second move
// arriving while already armed is a no-op `setArmed(true)` and the FIRST
// move's timer would fire mid-way through the second glide, snapping it.
const timer = window.setTimeout(
() => setArmed(false),
transitionDuration + 50
);
return () => window.clearTimeout(timer);
}, [armed, seenIndex, transitionDuration]);
useEffect(() => {
paintedRef.current = centered ? null : position ?? paintedRef.current;
});
const isStepMove = armed && !centered && activePos !== null;
// Not centered and never positioned yet → keep hidden until the first
// measure lands, so the box never flashes at (0, 0).
const measuring = !centered && activePos === null;
const wrapperStyle: React.CSSProperties | undefined = activePos
? { left: activePos.x, top: activePos.y }
: undefined;
const wrapperClass = clsx(
styles.tooltip,
centered && styles.centered,
measuring && styles.measuring,
// Transition ON only for a step move; snapped for first paint, live
// tracking, the re-measure window, and centered↔targeted switches.
!isStepMove && styles.noTransition,
classNames?.tooltip
);
if (renderStep) {
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
className={wrapperClass}
style={wrapperStyle}
data-tour-tooltip=""
data-placement={activePos?.placement}
>
{renderStep({
step,
index,
count,
controller,
gated,
tooltipProps: restTooltipProps,
})}
</div>
);
}
return (
<div
{...restTooltipProps}
ref={ref as React.Ref<HTMLDivElement>}
className={clsx(wrapperClass, styles.box)}
style={wrapperStyle}
data-tour-tooltip=""
data-placement={activePos?.placement}
>
{!centered && activePos && (
<Arrow
x={activePos.arrow.x}
y={activePos.arrow.y}
placement={activePos.placement}
className={classNames?.arrow}
/>
)}
{(step.title != null || showClose) && (
<div
className={clsx(styles.header, classNames?.header)}
data-tour-header=""
>
{step.title != null && (
<div className={styles.title} id={titleId}>
{step.title}
</div>
)}
{showClose && (
<button
type="button"
className={styles.close}
aria-label={labels.close}
onClick={controller.skip}
data-tour-close=""
>
×
</button>
)}
</div>
)}
<div
className={clsx(styles.content, classNames?.content)}
id={contentId}
data-tour-content=""
>
{step.content}
</div>
<div
className={clsx(styles.footer, classNames?.footer)}
data-tour-footer=""
>
{(showCounter || showProgress) && (
<div className={styles.meta}>
{showCounter && (
<span
className={clsx(styles.counter, classNames?.counter)}
data-tour-counter=""
>
{index + 1} / {count}
</span>
)}
{showProgress && (
<span
className={clsx(styles.dots, classNames?.dots)}
data-tour-dots=""
aria-hidden="true"
>
{Array.from({ length: count }, (_, dot) => (
<span
key={dot}
className={clsx(
styles.dot,
dot === index && styles.dotActive
)}
data-tour-dot={dot === index ? "active" : ""}
/>
))}
</span>
)}
</div>
)}
{showSkip && (
<button
type="button"
className={clsx(styles.button, styles.buttonSecondary)}
onClick={controller.skip}
data-tour-skip=""
>
{labels.skip}
</button>
)}
{!isFirst && (
<button
type="button"
className={clsx(styles.button, styles.buttonSecondary)}
onClick={controller.prev}
data-tour-back=""
>
{labels.back}
</button>
)}
{/* Gated steps keep Next visible but disabled — a hidden button reads
as a dead end; disabled + the hint below conveys what to do. The
onClick guard is belt-and-braces on top of `disabled`. */}
<button
type="button"
className={clsx(styles.button, styles.buttonPrimary)}
onClick={gated ? undefined : controller.next}
disabled={gated}
aria-disabled={gated || undefined}
data-tour-next=""
>
{isLast ? labels.finish : labels.next}
</button>
</div>
{gated && (
<div className={styles.gatedHint} data-tour-gated-hint="">
{labels.gatedHint}
</div>
)}
</div>
);
}
Tooltip.displayName = "SpotlightTourTooltip";
|