Calling destroy() on a driver that was never started or already
destroyed would strip body classes and highlights belonging to
another active instance.
Fixes#504
The built-in button always dismissed; repurposing it meant hiding it and
rebuilding one in onPopoverRender. onButtonClick (per hint or instance
wide, hint wins) now runs instead of dismissing, mirroring how a tour's
onNextClick takes over the default advance; call dismiss() from the hook
to keep the old behavior. Custom and extra buttons remain the
onPopoverRender pattern, same as tours.
show() now mounts hints whose elements have appeared since the last
call, which the docs already promised but only a full hide()/show()
delivered; mountHints() skips what is already on the page, making
show() naturally idempotent and simpler.
The closePopover()/close() pair collapses into one function, the
scroll and resize listeners use requireRefresh directly instead of
wrapper closures, and config/dismissed become consts.
Comments get a pass: the HintsConfig overlay comment still described
the pre-cutout semantics (beacons above the overlay) and is corrected;
obvious comments are dropped, the load-bearing ones tightened, and em
dashes across source comments replaced per Kamran's preference.
box-shadow follows the popover's rectangular box, so the protruding
arrow cast nothing and read as a flat notch against whatever sat behind
it. The hint popover now uses a drop-shadow filter instead, which
follows the rendered silhouette: the rounded box and the arrow cast a
single continuous shadow, with no border tricks and no assumptions
about the theme's colors. Tours are untouched since their overlay
already gives the arrow contrast.
With the overlay up, an open hint now reads exactly like a tour step:
the popover anchors to the element (clearing the cutout ring and lining
up with its edge) instead of hanging off the beacon, and the beacon
steps aside while its popover is up — the spotlight does the pointing.
Suggested by Kamran: once the dot has been clicked, it is just noise
inside the cutout. Without the overlay nothing changes; the dot remains
the anchor and the toggle. Dim-click, Escape and Got it all still close.
The hint arrow also grows to 14px (7px borders) — the tour's 10px
triangle read small next to a 24px beacon. Tours are untouched. The
arrow placement code now measures the arrow's real box instead of
assuming the constant, so restyled arrows keep their tip on target;
the beacon-shift constant is the one place the size is assumed, since
it runs before the popover exists.
The overlay is now the same spotlight the tour draws: an svg dim with a
rounded cutout around the open hint's element (the path generator moves
out of the tour's context into a pure function both share). The element
stays visible and interactive inside the cutout — the svg lets pointer
events through and only the dimmed path catches them, so clicking the
dim still closes the hint.
The other beacons now wait under the overlay instead of floating above
it; only the open hint's beacon (via its aria-expanded state) and its
popover rise above. The cutout tracks the element on scroll and resize.
The arrow's drop-shadow halo is gone: it read as a dirty outline against
light pages — tours never needed one because the arrow sits against the
dark overlay, and hints now either touch the colored beacon (no overlay)
or sit against the dim (overlay), so the plain white triangle works in
both.
Three fixes to how hints look and behave:
The popover arrow used to land beside the dot: it sits a fixed corner
inset from the popover's edge, while start/end alignment put the popover
edge flush with the beacon. The position options now pass the difference
between the arrow tip and the beacon's half-size as the alignment
pull-back, so the arrow points at the beacon's center. The arrow also
gets a faint halo — it is a white triangle designed to sit against a
tour's darkened overlay, and vanished on light pages without one.
The default beacon grows from 20px to 24px (still --driver-hint-size),
and defaults to a lighter indigo.
New opt-in overlay: overlay: true dims the page while a hint is open
(overlayColor/overlayOpacity to taste). Beacons and the popover sit
above it so hints stay clickable, and clicking the dimmed page closes
the hint like any outside click. Verified in a real browser — beacons
float above the dim, arrow centered on the dot.
packages/driver is the library (still published as driver.js, with
repository.directory set); playground and docs move to apps/. One root
pnpm workspace and lockfile replace the three standalone projects, with
turbo orchestrating build/test/lint:package (apps depend on the library
build; local + CI caching via .turbo).
Apps keep importing the library from source for HMR — the aliases now
point at ../../packages/driver/src and each app gains a workspace:*
dependency so the task graph knows the edge. The dev-server fs scope
widens to the repo root accordingly.
Releases run from packages/driver (root `pnpm release` delegates). The
changelog still lives in the docs app, so the release scripts reach it
via ../../../apps/docs and the after:bump hook stages it explicitly —
release-it no longer sits above both directories.
The merged workspace settings keep sharp unbuilt on purpose (prebuilt
binaries; building from source needs node-gyp and fails) — the docs app
had this right and the playground setting was the accident. postcss and
postcss-scss were unreferenced devDependencies and are dropped; prettier
moves to the root as the only shared tool.
Kamran Ahmed