feat(scrollspy): the "on this page" rail

[mplatts]

Closes #613

Summary

A new <.scrollspy> component plus a PetalScrollspy hook: the docs "on this page" rail that follows the reader down a long article.

Two APIs, both first-class in the moduledoc:

1. The built-in renderer. Pass items (label + target id, optionally one level of children), get a <nav> with an animated indicator bar. offset, threshold, indicator (bar / none), heading, aria_label, class, rest.
2. The bare data-attribute contract. phx-hook="PetalScrollspy" on any container whose links carry data-scrollspy-target, and the hook drives your own markup. It sets aria-current="location" and pc-scrollspy-link--active on the active link and nothing else. Zero pc-scrollspy classes needed.

The hook uses an IntersectionObserver over a reading band near the top of the viewport, but only as a trigger - every decision is recomputed from live rects. That keeps the rail honest when a section grows, the window resizes, or a LiveView patch swaps the content, and it makes the selection logic a pure function.

Files

File	What
lib/petal_components/scrollspy.ex	new component
lib/petal_components/showcase/scrollspy.ex	3 registry examples (basic, nested, bare markup)
assets/js/petal_components.js	PetalScrollspy hook + exported scrollspyActive/2
assets/default.css	pc-scrollspy section, inside @layer components
dev.exs	/c/scrollspy playground: a real mini guide with offset / nesting / indicator dials
test/petal/scrollspy_test.exs	19 component tests
test/js/scrollspy.test.js	22 vitest specs
lib/petal_components.ex, showcase/registry.ex, CHANGELOG.md	registration

Deviations from the issue's API sketch

• Added an aria_label attr (default "On this page"). The sketch hardcoded aria-label next to {@rest}; since rest is a global, a consumer passing their own aria-label would have produced a duplicate attribute on the element. An explicit attr is the only way to let them override it.
• "topmost wins" is implemented as "the last section to have reached the activation line". Read literally, "closest to the top of the viewport" is ambiguous when three short sections are all crowded above the line. The rule shipped is: among the sections that have reached the line, the one furthest down the page wins - i.e. the section that owns the reading position. It agrees with the issue's example cases and is unambiguous in the crowded one. Both are covered in the spec.
• The nav carries a pc-scrollspy--bar / pc-scrollspy--none modifier. The rail line is drawn on the list only in bar mode, so indicator="none" is genuinely a plain text list rather than a railed one with the bar removed.
• Nested children render in a pc-scrollspy__sublist <ul> inside the parent <li>. The sketch only named the link class; the sublist element is what makes the nesting real markup rather than indentation.
• The selection logic is a named export, scrollspyActive(sections, {line, atBottom}), alongside the hook object. That is what lets the vitest suite test the behaviour directly rather than through a fake observer.
• Bottom snap only fires on a container that actually scrolls. Without that guard a short page whose content fits entirely on screen would highlight its last entry forever, which is not a bottom any reader would recognise.
• Default rootMargin is -25% 0px -70% 0px (activation line at 25% of the viewport), overridable via data-threshold exactly as specified.

Observer cleanup

destroyed() disconnects the observer, removes the hashchange and resize listeners from window, detaches the scroll listener from the scroll root, cancels any pending requestAnimationFrame, and restores every style the hook borrowed - the container's previous scroll-behavior and each target's previous inline scroll-margin-top. scan() disconnects the old observer before creating a new one, and the scroll listener moves with the scroll root rather than being left on the old one when a patch relocates the sections. There is a spec that destroys a hook and then fires a hashchange to prove the stale hook no longer drives the page.

The scroll listener exists because bottom snap is invisible to the observer: a closing section too short to reach the activation line never generates a callback. It is passive and coalesced to one pass per animation frame.

Reduced motion and smooth scroll

Smooth scrolling is a property of the scroll container, not of the click, so the hook sets scroll-behavior: smooth on the scroll root at mount and puts the previous value back on destroy. Under prefers-reduced-motion: reduce it never sets it at all, so jumps are instant. The indicator bar is positioned by JS (transform + height) and animated by CSS, which means the reduced-motion opt-out for the transition is one media query in default.css - the bar still tracks the active link, it just arrives without the glide. Scrolling never moves focus in either case.

Tests

Suite	Before	After
mix test	913 tests, 0 failures, 1 skipped	932 tests, 0 failures, 1 skipped
npm test	157 passing	179 passing

mix format --check-formatted, mix compile --force --warnings-as-errors and mix credo are all clean - credo reports the same 14 refactoring opportunities / 31 readability issues as main, so zero new entries.

Screenshots

Captured and eyeballed locally at 1280x1800 on /c/scrollspy: light, dark, and a scrolled shot where a non-first entry is active (a scrollspy screenshot with the first item highlighted proves nothing). Verified in both schemes that the active link reads stronger than the rest, the indicator sits against it, the nested example indents correctly, and the bare-markup example highlights with no pc-scrollspy classes on it. Images are not committed - happy to attach them to this thread on request.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.44%. Comparing base (871b2cf) to head (c5fa3d9).
⚠️ Report is 24 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #631      +/-   ##
==========================================
+ Coverage   92.40%   92.44%   +0.04%     
==========================================
  Files         119      121       +2     
  Lines        5066     5094      +28     
==========================================
+ Hits         4681     4709      +28     
  Misses        385      385              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mplatts]

Screenshots

Tracking a non-first section — scrolled so "Wiring it up" owns the reading position. The indicator bar sits beside it, and the nested example below tracks independently.

Light

Dark

Verified independently

Check	Result
mix test	932 tests, 0 failures, 1 skipped (+19)
npm test	179 passing (+22)
mix format --check-formatted	clean
mix compile --force --warnings-as-errors	clean
mix credo	zero new entries vs main
new dependencies	none
slugs : render_page clauses	61 : 61

The dark:text-primary-400 → primary-300 fix is a good catch and the kind of thing that only shows up if you actually look: with the playground's default neutral primary, 400 lands at the same lightness as gray-400, so the active state was invisible in dark mode. 300 is also the more common convention in default.css (10 uses vs 7).

Two decisions worth a maintainer eye, both flagged in the PR body: "topmost wins" was ambiguous in the issue and shipped as "the last section to reach the activation line"; and a passive scroll listener rides alongside the observer because bottom-snap is invisible to IntersectionObserver by construction.

Gaps the author was straight about: keyboard-only, prefers-reduced-motion and hash-on-load are covered by unit specs but were not clicked through in a real browser.

_{Images live on the pr-assets branch, which exists only to host PR screenshots - it never merges to main and ships in no Hex release.}

[greptile-apps]

Greptile Summary

Adds a public scrollspy component, its LiveView hook, styling, showcase registration, playground, and component/JavaScript tests.

• Renders flat or one-level nested in-page navigation with active-link and indicator states.
• Tracks page or overflow-pane scrolling, hash navigation, offsets, reduced-motion preferences, and LiveView updates.
• Registers the component and hook through the package’s public Elixir and JavaScript entry points.

Confidence Score: 2/5

The PR should not merge until reduced-motion behavior, patched offset cleanup, and malformed-fragment handling are corrected.

The stylesheet re-enables collapsible animation for reduced-motion users, while the hook can retain stale target spacing after LiveView updates and abort synchronization on malformed URL fragments.

Files Needing Attention: assets/default.css, assets/js/petal_components.js

Important Files Changed

Filename	Overview
assets/js/petal_components.js	Adds the complete scrollspy lifecycle and selection behavior, but update-time style cleanup and malformed-fragment handling can fail.
assets/default.css	Adds scrollspy presentation and reduced-motion rules while accidentally deleting the existing collapsible reduced-motion declaration.
lib/petal_components/scrollspy.ex	Introduces the documented public HEEx renderer, attributes, nested item markup, and hook data contract.
test/js/scrollspy.test.js	Provides broad selection, lifecycle, cleanup, pane, and accessibility-state coverage but omits offset-removal and malformed-hash paths.
test/petal/scrollspy_test.exs	Covers the component’s rendered markup, supported variants, attributes, and item structures.

Sequence Diagram

sequenceDiagram
  participant LV as LiveView
  participant Nav as Scrollspy nav
  participant Hook as PetalScrollspy
  participant Sections as Article sections
  participant Browser as Browser scroll/hash
  LV->>Nav: Render links and data attributes
  Nav->>Hook: Mount phx-hook
  Hook->>Sections: Resolve targets and apply offset
  Hook->>Browser: Observe sections and listen for scroll/hash
  Browser->>Hook: Scroll, resize, or hashchange
  Hook->>Sections: Read live section positions
  Hook->>Nav: Set active class, aria-current, and indicator
  LV->>Nav: Patch attributes or links
  Nav->>Hook: updated()
  Hook->>Sections: Rescan targets and synchronize state

Loading

_{Reviews (1): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[greptile-apps]

Reduced-motion rule emptied

When a user enables reduced motion, this now-empty rule leaves the collapsible panel and chevron transitions active, causing those elements to continue animating despite the operating-system preference.

Suggested change

	@media (prefers-reduced-motion: reduce) {
	.pc-collapsible__panel,
	.pc-collapsible__chevron {
	}
	}
	@media (prefers-reduced-motion: reduce) {
	.pc-collapsible__panel,
	.pc-collapsible__chevron {
	transition: none;
	}
	}

[greptile-apps]

Patched offsets leave stale styles

When a LiveView patch clears data-offset or removes a previously linked target while preserving the hook, scan() never restores the borrowed scroll-margin-top, causing later anchor navigation to land with stale spacing.

Knowledge Base Used: Browser hooks

[greptile-apps]

Malformed hashes abort synchronization

When the page loads or receives a hashchange containing a malformed percent escape, decodeURIComponent throws before synchronization runs, causing the scrollspy to fail to initialize or refresh its active state.

Suggested change

	applyHash() {
	const id = decodeURIComponent(window.location.hash.replace(/^#/, ""));
	if (!id || !this.targets?.some((target) => target.id === id)) return false;
	applyHash() {
	let id;
	try {
	id = decodeURIComponent(window.location.hash.replace(/^#/, ""));
	} catch {
	return false;
	}
	if (!id || !this.targets?.some((target) => target.id === id)) return false;

Knowledge Base Used: Browser hooks