@wcstack/intersection

@wcstack/intersection

@wcstack/intersection is a headless IntersectionObserver component for the wcstack ecosystem.

It is not a visual UI widget. It is an async primitive node that turns an element's visibility into reactive state — the same way @wcstack/fetch turns a network request into reactive state and @wcstack/geolocation turns the device's location into reactive state.

With @wcstack/state, <wcs-intersect> can be bound directly through path contracts:

• input / command surface: target, root, root-margin, threshold, once, manual, trigger
• output state surface: entry, intersecting, ratio, visible, observing

This means visibility-aware work — lazy-loading, infinite scroll, scroll-spying — can be expressed declaratively in HTML, without writing new IntersectionObserver(), observe(), disconnect(), or teardown glue in your UI layer.

@wcstack/intersection follows the CSBC (Core / Shell / Binding Contract) architecture:

• Core (IntersectionCore) owns the observer, entry normalization, the visible latch, and observation lifecycle
• Shell (<wcs-intersect>) resolves what to observe from the DOM, manages display, lifecycle, and declarative commands
• Binding Contract (static wcBindable) declares observable properties, writable inputs, and callable commands

Why this exists

IntersectionObserver is different from every other @wcstack sensor: the thing it observes is a DOM element, not a headless resource. Imperatively, wiring it up means creating an observer, resolving a target node, handling the entry callback, and tearing it all down on disconnect.

@wcstack/intersection moves that logic into a reusable component and exposes the result as bindable state. An element scrolling into view becomes a state transition, not imperative callback wiring. It is a read-only producer: the element/layout only produces values for the state (element/layout → state), with no path back.

The target attribute decides everything

target is the single knob that selects what is observed — and, with it, how <wcs-intersect> renders. It never injects a layout box unless you explicitly ask for one:

target	observes	display	use case
omitted	first element child	contents	lazy-load wrapper
"#hero" / sel.	the matched element	none	scrollspy (single)
"self"	the element itself	block	infinite-scroll edge

display:contents means wrapping a child injects no box of its own — so <wcs-intersect><img></wcs-intersect> does not disturb a flex/grid parent. Only the explicit target="self" sentinel takes a box.

First element child. When target is omitted, the first element child is observed. The target is re-resolved on every observe() (which runs on connect and on each observed-attribute change), so adding or removing the first child after connect switches the observed element on the next re-observe. If there is no element child at resolution time, it falls back to observing itself (display:block). Observing multiple targets at once is intentionally out of scope — wrap each target in its own <wcs-intersect>.

Install

npm install @wcstack/intersection

Quick Start

1. Lazy-load an image (visible latch)

visible flips to true the first time the target intersects and stays true. Bind the image src to it and the image only loads once it scrolls into view.

<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
<script type="module" src="https://esm.run/@wcstack/intersection/auto"></script>

<wcs-state>
  <script type="module">
    export default {
      shown: false,
      get src() {
        return this.shown ? "/photo.jpg" : "";
      }
    };
  </script>
</wcs-state>

<wcs-intersect once data-wcs="visible: shown">
  <img data-wcs="src: src" alt="lazy">
</wcs-intersect>

once disconnects the observer after the first intersection — ideal for one-shot lazy loads.

2. Infinite scroll (sentinel)

Place an empty target="self" marker at the bottom of a list; bind intersecting to a state flag that triggers loading more.

<ul data-wcs="for: items">
  <li data-wcs="textContent: items.*.name"></li>
</ul>

<wcs-intersect target="self" data-wcs="intersecting: atEnd"></wcs-intersect>

export default {
  items: [],
  atEnd: false,
  get _loadMore() {
    // a computed/effect that reacts to atEnd becoming true
    return this.atEnd ? fetchNextPage() : null;
  }
};

3. Scrollspy (single section)

Point target at a section elsewhere in the document; bind intersecting to highlight the matching nav item.

<nav>
  <a href="#features" data-wcs="class.active: featuresVisible">Features</a>
</nav>

<section id="features">…</section>

<wcs-intersect target="#features" threshold="0.5"
  data-wcs="intersecting: featuresVisible"></wcs-intersect>

Attributes

Attribute	Type	Default	Description
target	string	(omitted)	What to observe: omitted → first child, a selector → that element, self → this element.
root	string	(viewport)	Selector for the scroll root.
root-margin	string	0px	Margin around the root (CSS-margin syntax).
threshold	string	0	A single ratio (0.5) or comma list (0,0.5,1) of 0..1 thresholds. Invalid / out-of-range values are dropped.
once	boolean	false	Disconnect after the first intersecting observation.
manual	boolean	false	Do not auto-observe on connect; drive it via commands instead.

trigger has no attribute — it is a momentary command-property meant for @wcstack/state wiring only. A false → true write re-runs observe() and the property auto-resets to false (a one-shot acknowledgement; read observing for the actual outcome). Prefer the command-token protocol (command.observe: …) over this boolean for state-driven observation.

Output state

Property	Type	Description
entry	WcsIntersectEntry | null	Plain snapshot of the latest IntersectionObserverEntry (rects normalized to plain numbers), plus the live target node.
intersecting	boolean	Whether the target currently intersects the root.
ratio	number	The latest intersectionRatio.
visible	boolean	Latch: true once the target has intersected; cleared only by reset().
observing	boolean	Whether an observation is currently active.

Commands

Command	Description
observe()	Re-resolve target / root from the DOM and (re)start observing. Idempotent: an unchanged target+options is a no-op (no fresh callback).
reobserve()	Force a fresh observation even when target / options are unchanged — tears the observer down and rebuilds it, so a new initial callback fires for the current visibility. Use to re-arm an edge-driven consumer (e.g. infinite scroll) after the layout shifted without a visibility transition. observing stays true across a successful re-arm (no false blip).
unobserve()	Stop observing the current target.
disconnect()	Stop all observation.
reset()	Clear the visible latch so a later intersection can set it again.

Binding Contract (wcBindable)

Both the Core and the Shell declare the wc-bindable protocol.

// IntersectionCore (headless)
IntersectionCore.wcBindable = {
  protocol: "wc-bindable",
  version: 1,
  properties: [
    { name: "entry", event: "wcs-intersect:change" },
    { name: "intersecting", event: "wcs-intersect:change", getter: (e) => e.detail.isIntersecting },
    { name: "ratio", event: "wcs-intersect:change", getter: (e) => e.detail.intersectionRatio },
    { name: "visible", event: "wcs-intersect:visible-changed" },
    { name: "observing", event: "wcs-intersect:observing-changed" },
  ],
  commands: [
    { name: "observe" }, { name: "reobserve" }, { name: "unobserve" }, { name: "disconnect" }, { name: "reset" },
  ],
};

The Shell (<wcs-intersect>) inherits the Core's properties / commands, adds the momentary trigger property, and declares the DOM-driven inputs (target, root, rootMargin, threshold, once, manual, trigger).

Using the Core standalone

IntersectionCore is framework-agnostic and can be used without the custom element. You hand it the element to observe (the Shell does this resolution for you):

import { IntersectionCore } from "@wcstack/intersection";

const core = new IntersectionCore();
core.addEventListener("wcs-intersect:change", (e) => {
  console.log(e.detail.isIntersecting, e.detail.intersectionRatio);
});
core.observe(document.querySelector("#hero"), { threshold: [0, 0.5, 1] });
// later
core.disconnect();

Notes & limitations

• Single target. Each <wcs-intersect> observes exactly one element so the state maps to a single value surface. For many targets, use many elements.
• Never throws. Unsupported environments (no IntersectionObserver) and invalid options (e.g. a malformed root-margin) are silent no-ops: observing stays false rather than throwing.
• No permission gate / secure context requirement (unlike @wcstack/geolocation).

License

MIT