Scroll Sentinel

---
// src/components/ui/utility/scroll-sentinel/ScrollSentinel.astro — headless primitive (see ../../README.md).
// The load-more trigger for an infinite list — and the two things that make infinite scrolling
// usable rather than merely fashionable.
//
// FIRST: there is a real <button>. The observer does not call your loader; it CLICKS the button, so
// pointer, keyboard and screen reader all travel the same code path and a user who never scrolls
// with a mouse wheel can still reach the next page. An infinite list with no button is a list a
// keyboard user cannot finish.
//
// SECOND: there is a live region. Appending rows to a list moves no focus and fires no announcement,
// so without one a screen reader user hears silence and has no idea whether anything happened.
//
//   <ScrollSentinel>
//     <button type="button" data-slot="scroll-sentinel-trigger">Load more</button>
//   </ScrollSentinel>
//
// Wire it by listening for a click on that button. While loading, set `disabled` on it — the
// observer stands down for a disabled trigger, which is what stops a slow request being fired twice.
// When the last page has arrived, leave it disabled (or hidden) and write the outcome into
// `[data-slot="scroll-sentinel-status"]`; this component announces the START of a load and nothing
// else, because only the consumer knows how it ended.
import type { HTMLAttributes } from "astro/types";

type Props = HTMLAttributes<"div"> & {
  /** How far ahead of the viewport loading starts — any CSS margin string. */
  rootMargin?: string;
  /** Announced when a load begins. */
  loadingLabel?: string;
};

const {
  rootMargin = "200px",
  loadingLabel = "Loading more items…",
  class: className,
  ...rest
} = Astro.props;
---

<div class={className} data-slot="scroll-sentinel" data-root-margin={rootMargin} {...rest}>
  <slot>
    <button type="button" data-slot="scroll-sentinel-trigger">Load more</button>
  </slot>
  <p role="status" data-slot="scroll-sentinel-status" data-loading-label={loadingLabel}></p>
</div>

<script>
  import { onReadyOnce } from "../../_once";

  function wire(root: HTMLElement) {
    const trigger = root.querySelector<HTMLButtonElement>('[data-slot="scroll-sentinel-trigger"]');
    if (!trigger) return;
    const status = root.querySelector<HTMLElement>('[data-slot="scroll-sentinel-status"]');

    // Announce on ACTIVATION, not on intersection, so a click and a scroll say the same thing. The
    // consumer's own click handler runs after this one and is free to overwrite the message.
    trigger.addEventListener("click", () => {
      if (status) status.textContent = status.dataset.loadingLabel ?? "";
    });

    new IntersectionObserver(
      (entries) => {
        if (!entries.some((entry) => entry.isIntersecting)) return;
        // `disabled` is the consumer's "a request is already in flight, or there is nothing left".
        if (trigger.disabled || trigger.hidden) return;
        trigger.click();
      },
      { rootMargin: root.dataset.rootMargin || "0px" },
    ).observe(root);
  }

  onReadyOnce('[data-slot="scroll-sentinel"]', wire);
</script>

import ScrollSentinel from "./ScrollSentinel.astro";

export { ScrollSentinel };
export default ScrollSentinel;