Scroll Snap

/* The whole page snaps. For a nested scroller, move the html rules onto it,
   give it a fixed height and overflow-y: auto, and use that height for 100svh. */
:root {
  --header: 0px; /* a fixed header's height, e.g. 56px */
}

html {
  scroll-snap-type: y mandatory;
  /* Panels rest under the header, not behind it. */
  scroll-padding-top: var(--header);
  /* Top: the first panel starts below the header. Bottom: the snap area's
     height minus a panel's, so the last panel can rest at the top too. */
  padding-block: var(--header) 48px;
}

body {
  margin: 0;
}

.panel {
  scroll-snap-align: start;
  /* The snap area (viewport minus header) less 48px: the 8px gap and the
     edge of the next panel show. Never taller than the snap area. */
  height: calc(100svh - var(--header) - 48px);
  /* normal lets a fast fling pass panels. always: none can be skipped. */
  scroll-snap-stop: normal;
}

.panel + .panel {
  margin-top: 8px;
}

/* Nested scroller only: the page behind stays put at either end.
   .snap { overscroll-behavior-y: contain; } */

/* Snapping stays under reduced motion: it is where scrolling rests, not an
   animation. Only the glide (scroll-behavior: smooth, where set) goes. */
@media (prefers-reduced-motion: reduce) {
  html { scroll-behavior: auto; }
}

// Prev/next buttons and the current panel. Scrolling and snapping are all CSS:
// no wheel or touch listeners, nothing that fights the browser.
// Markup: <button data-prev aria-label="Previous panel">
//         <button data-next aria-label="Next panel">
const panels = [...document.querySelectorAll('.panel')]
const prev = document.querySelector('[data-prev]')
const next = document.querySelector('[data-next]')
const reduce = matchMedia('(prefers-reduced-motion: reduce)')
let current = 0

function show(i) {
  current = i
  prev.disabled = i === 0
  next.disabled = i === panels.length - 1
}

function go(i) {
  const target = Math.min(Math.max(i, 0), panels.length - 1)
  // From the target, not the panel on screen, so a quick double click moves two.
  show(target)
  // scrollIntoView respects scroll-padding. Under reduced motion the glide goes; the snap stays.
  // Nested scroller: this would scroll the page too. Use scroller.scrollTo with the panel's
  // offsetTop minus the scroller's padding-top (the scroller is position: relative).
  panels[target].scrollIntoView({ block: 'start', behavior: reduce.matches ? 'instant' : 'smooth' })
}

// The panel at rest: its top nearest the top of the area below the header.
function nearest() {
  const header = parseFloat(getComputedStyle(document.documentElement).scrollPaddingTop) || 0
  const off = (p) => Math.abs(p.getBoundingClientRect().top - header)
  return panels.reduce((best, p, i) => (off(p) < off(panels[best]) ? i : best), 0)
}

prev.addEventListener('click', () => go(current - 1))
next.addEventListener('click', () => go(current + 1))

if ('onscrollsnapchange' in window) {
  // Chromium 129+: fires when a scroll comes to rest on a different snap target.
  // A nested scroller fires it on itself, not on document: listen there.
  // The target is null when a scroll rests between two panels (proximity).
  document.addEventListener('scrollsnapchange', (e) => {
    show(e.snapTargetBlock ? panels.indexOf(e.snapTargetBlock) : nearest())
  })
} else if ('onscrollend' in window) {
  addEventListener('scrollend', () => show(nearest()))
} else {
  let idle = 0
  const settle = () => {
    clearTimeout(idle)
    idle = setTimeout(() => show(nearest()), 100)
  }
  addEventListener('scroll', settle, { passive: true })
}
// A reload can restore the scroll position on any panel.
show(nearest())