TOC block: clicking an entry highlights the previous entry, not the one clicked (scroll-spy offset rounding)

[georgestephanis]

Summary

When a Table of Contents block has both Smooth Scroll and Scroll Spy enabled, clicking an entry scrolls to the right heading, but the previous entry stays marked active instead of the one just clicked. It self-corrects on the next manual scroll.

Root cause

src/assets/js/kb-table-of-contents.js, scrollToElement():

const originalTop = Math.floor(element.getBoundingClientRect().top) - offset;
window.scrollBy({ top: originalTop, left: 0, behavior: 'smooth' });

Math.floor truncates the fractional part of rect.top before subtracting offset, so the computed scroll distance always slightly undershoots. After the smooth scroll settles, the heading's top ends up a fraction of a pixel above offset, not at-or-below it.

src/assets/js/gumshoe.js (bundled scroll-spy library) decides which entry is active with:

return parseInt(bounds.top, 10) <= offset;

Because the click-scroll landed just above offset, this check fails for the just-scrolled-to heading, so Gumshoe keeps the previously-active entry highlighted until the user scrolls manually (which recomputes on real scroll-event polling and self-corrects).

Confirmed present on master @ da98205 (2026-08-05) — not something already fixed since a recent release.

Steps to reproduce

1. Add a Table of Contents block to a post with several headings.
2. Enable Smooth Scroll and Scroll Spy.
3. On the front end, click a TOC entry that isn't the first one.
4. Observe: the scroll lands correctly, but the previous entry (or none) stays highlighted instead of the one clicked, until you scroll manually.

Proposed fix

I've opened a PR that (a) fixes the rounding in scrollToElement(), and (b) replaces the bundled Gumshoe scroll-event-polling scroll-spy with a native IntersectionObserver implementation for this block (~96% global browser support per caniuse.com, W3C polyfill available for the remainder) — scoped only to the TOC block; the navigation block's own separate Gumshoe-based scroll-spy usage (src/assets/js/kb-navigation-block.js) is untouched and could be a good candidate for the same treatment in a follow-up if maintainers are interested.

AI disclosure

This issue was drafted with the assistance of Claude (Anthropic's AI coding assistant), operating under my direction and review. Claude located and read the relevant source in this repo, traced the root cause across kb-table-of-contents.js and gumshoe.js, confirmed against the current master commit that the bug was still present, and drafted this writeup. I reviewed the analysis and code excerpts before posting.

[georgestephanis]

Correction: my original root-cause analysis above is wrong

Coming back to this after it resurfaced downstream. The Math.floor rounding I
described is real but it is not what causes this — it accounts for a
sub-pixel difference, and the actual gap I measured is ~41px. Apologies for
sending anyone down that path; the details below supersede the original report.

What's actually happening

With Kadence Blocks and the Kadence theme both active, a TOC click fires
two competing smooth scrolls ~4ms apart, from two different products.
Captured stack traces (Blocks 3.7.10, theme 1.5.2):

--- call 1: scrollBy({"top":3260,"behavior":"smooth"}) ---
    at Object.scrollToElement   (kadence-blocks/includes/assets/js/kb-table-of-contents.min.js)
    at d.<computed>.onclick     (kadence-blocks/includes/assets/js/kb-table-of-contents.min.js)

--- call 2: scrollBy({"top":3280,"behavior":"smooth"}) ---
    at Object.scrollToElement   (themes/kadence/assets/js/navigation.min.js)
    at Object.anchorScrollToCheck (themes/kadence/assets/js/navigation.min.js)
    at HTMLAnchorElement.<anonymous> (themes/kadence/assets/js/navigation.min.js)

Both bind to the same TOC anchors, each with its own offset:

• the block scrolls using the block's data-scroll-offset
• the theme (anchorScrollToCheck) scrolls using its own sticky-header-aware
  offset — the sticky header's height, plus a hardcoded 32 for the admin bar:
  document.body.classList.contains( 'admin-bar' ) && ( e = 32 )

The theme's call is issued last, so it cancels the block's in-flight smooth
scroll and wins. The page therefore comes to rest at the theme's offset.

Gumshoe, however, is initialised with the block's data-scroll-offset:

new Gumshoe( selector, { offset() { return a ? a : 0 } } )   // a = data-scroll-offset

and picks the active entry with parseInt( bounds.top, 10 ) <= offset. So the
threshold is derived from one source while the scroll position is decided by
another. On a site with an 80px sticky header and data-scroll-offset at its
default 40, the heading rests at 81 and 81 <= 40 is false — the previously
active entry stays highlighted until the next manual scroll.

Measured on a real site, clicking the same entry while only varying the spy offset:

data-scroll-offset	resting rect.top	top <= offset	active entry
40 (default)	81	false	previous entry ❌
80	81	true	correct ✅
100	81	true	correct ✅

Logged in, the theme adds 32 for the admin bar, the heading rests at 113, and
anything below that regresses again — which is why this reads as intermittent:
it behaves differently for logged-in editors than for logged-out visitors.

Is it still worth fixing upstream?

I think yes, more than the original report suggested. This is not an exotic
edge case — it's the default Kadence theme + Kadence Blocks pairing with a
sticky header, and the symptom (scroll-spy highlighting the wrong entry) appears
on every TOC click. It also can't be fully solved by the site owner: tuning
data-scroll-offset to match the theme's offset works, but it's a hidden
coupling to a number the theme computes, and it breaks again whenever the sticky
header height or admin bar state changes.

Worth noting the two scrolls racing is itself undesirable independent of the
highlight bug — one scrollBy cancelling another mid-animation is why the
landing position is hard to reason about in the first place.

Possible directions

1. Don't double-handle the click. If the theme's anchorScrollToCheck is
   going to scroll the anchor, the block arguably shouldn't also scroll it.
   Detecting and deferring would remove the race entirely.
2. Decouple the spy threshold from the scroll setting. Rather than feeding
   Gumshoe the authored data-scroll-offset, derive the threshold from where
   headings actually come to rest (sticky header height + admin bar), or give
   offset() a live computation instead of a value captured at init.
3. Let the click win, regardless of offsets — on click, mark the clicked
   entry active immediately and suppress spy updates until the scroll settles.
   This makes correctness independent of any offset agreement between products,
   and would survive any future third party that also offsets anchor scrolling.

(3) seems the most robust to me, and is the smallest behavioural change for
existing sites.

About #1256

That PR implements the Math.floor → Math.ceil fix from the original
(incorrect) diagnosis, so its premise no longer holds — it doesn't address the
competing-scroll mismatch and shouldn't be merged as a fix for this. Happy to
close it, or rework it along the lines of (3) if that direction seems
reasonable. The IntersectionObserver swap bundled into it is a separate
question and could stand or fall on its own merits.

For anyone hitting this meanwhile, the downstream workaround is to raise the
block's data-scroll-offset to match the theme's real resting offset (sticky
header height, plus the admin bar's height for logged-in users, which varies
32px/46px by viewport).