svelte-intersection-observer 2.0.0 → 2.2.0

package/create-intersection-observer.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Attachment } from "svelte/attachments";
+import type { IntersectActionOptions } from "./intersect.svelte.js";
+
+export interface IntersectionObserverState {
+  /** `true` if the observed element is intersecting the viewport. */
+  readonly intersecting: boolean;
+
+  /** Observed element metadata. */
+  readonly entry: null | IntersectionObserverEntry;
+
+  /** Attachment to apply to the observed element via `{@attach}`. */
+  attach: Attachment<HTMLElement>;
+}
+
+/**
+ * Rune-based composable that observes the attached element with the
+ * Intersection Observer API, without a wrapper component or `use:`/`{@attach}`
+ * directive of your own.
+ */
+export function createIntersectionObserver(
+  getOptions?: () => IntersectActionOptions,
+): IntersectionObserverState;

package/create-intersection-observer.svelte.js

@@ -0,0 +1,36 @@
+import { intersectAttachment } from "./intersect.svelte.js";
+
+export function createIntersectionObserver(getOptions = () => ({})) {
+  let intersecting = $state(false);
+  let entry = $state( (null));
+
+  const attachment = intersectAttachment(getOptions);
+
+  function attach(node) {
+    const onObserve = (event) => {
+      const detail =  (
+        event
+      ).detail;
+      entry = detail;
+      intersecting = detail.isIntersecting;
+    };
+
+    node.addEventListener("observe", onObserve);
+    const cleanup = attachment(node);
+
+    return () => {
+      node.removeEventListener("observe", onObserve);
+      if (typeof cleanup === "function") cleanup();
+    };
+  }
+
+  return {
+    get intersecting() {
+      return intersecting;
+    },
+    get entry() {
+      return entry;
+    },
+    attach,
+  };
+}

package/index.d.ts

@@ -1,4 +1,15 @@
+export type { IntersectionObserverState } from "./create-intersection-observer.svelte.js";
+export { createIntersectionObserver } from "./create-intersection-observer.svelte.js";
 export { default } from "./IntersectionObserver.svelte";
-export type { IntersectActionOptions } from "./intersect.svelte.js";
-export { intersect } from "./intersect.svelte.js";
+export type {
+  IntersectActionOptions,
+  IntersectGroupNodeOptions,
+  IntersectGroupSharedOptions,
+  IntersectionGroup,
+} from "./intersect.svelte.js";
+export {
+  createIntersectionGroup,
+  intersect,
+  intersectAttachment,
+} from "./intersect.svelte.js";
 export { default as MultipleIntersectionObserver } from "./MultipleIntersectionObserver.svelte";

package/index.js

@@ -1,3 +1,8 @@
+export { createIntersectionObserver } from "./create-intersection-observer.svelte.js";
 export { default } from "./IntersectionObserver.svelte";
-export { intersect } from "./intersect.svelte.js";
+export {
+  createIntersectionGroup,
+  intersect,
+  intersectAttachment,
+} from "./intersect.svelte.js";
 export { default as MultipleIntersectionObserver } from "./MultipleIntersectionObserver.svelte";

package/intersect.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { Action } from "svelte/action";
+import type { Attachment } from "svelte/attachments";
 
 export interface IntersectActionOptions {
   /**
@@ -51,3 +52,92 @@ export const intersect: Action<
     ) => void;
   }
 >;
+
+/**
+ * Svelte attachment that observes the element with the Intersection Observer
+ * API. Equivalent to `intersect`, for use with `{@attach}` instead of `use:`.
+ */
+export function intersectAttachment(
+  getOptions?: () => IntersectActionOptions,
+): Attachment<HTMLElement>;
+
+declare module "svelte/elements" {
+  export interface HTMLAttributes<T> {
+    onobserve?: (event: CustomEvent<IntersectionObserverEntry>) => void;
+    onintersect?: (
+      event: CustomEvent<IntersectionObserverEntry & { isIntersecting: true }>,
+    ) => void;
+  }
+}
+
+/**
+ * Options shared by every node in an `createIntersectionGroup` group. These
+ * configure the one underlying `IntersectionObserver` instance, so they
+ * can't vary per node.
+ */
+export interface IntersectGroupSharedOptions {
+  /**
+   * Specify the containing element.
+   * Defaults to the browser viewport.
+   * @default null
+   */
+  root?: null | HTMLElement;
+
+  /**
+   * Margin offset of the containing element.
+   * @default "0px"
+   */
+  rootMargin?: string;
+
+  /**
+   * Percentage of element visibility to trigger an event.
+   * Value must be a number between 0 and 1, or an array of numbers between 0 and 1.
+   * @default 0
+   */
+  threshold?: number | number[];
+}
+
+/**
+ * Per-node options for a single element within an `createIntersectionGroup` group.
+ */
+export interface IntersectGroupNodeOptions {
+  /**
+   * Set to `true` to unobserve the element
+   * after it intersects the viewport.
+   * @default false
+   */
+  once?: boolean;
+
+  /**
+   * Set to `true` to skip observing this element without
+   * affecting the rest of the group.
+   * @default false
+   */
+  skip?: boolean;
+
+  /** Called when the element is first observed and also whenever an intersection change occurs. */
+  onobserve?: (entry: IntersectionObserverEntry) => void;
+
+  /** Called only when the element is intersecting the viewport. */
+  onintersect?: (
+    entry: IntersectionObserverEntry & { isIntersecting: true },
+  ) => void;
+}
+
+export interface IntersectionGroup {
+  /**
+   * Returns an attachment for a single node in the group. Call once per
+   * element in a loop, e.g. `{@attach group.attach({ onobserve })}`.
+   */
+  attach(options?: IntersectGroupNodeOptions): Attachment<HTMLElement>;
+}
+
+/**
+ * Creates a group of elements backed by a single shared `IntersectionObserver`
+ * instance, for use with `{@attach}` inside an `#each` block. Brings
+ * `MultipleIntersectionObserver`'s single-observer performance benefit to the
+ * action/attachment API.
+ */
+export function createIntersectionGroup(
+  getSharedOptions?: () => IntersectGroupSharedOptions,
+): IntersectionGroup;

package/intersect.svelte.js

@@ -1,10 +1,5 @@
-/**
- * Svelte action that observes `node` with the Intersection Observer API.
- * Dispatches `observe` (on every change) and `intersect` (on entering the
- * viewport) `CustomEvent`s on `node` — listen with `onobserve`/`onintersect`.
- * @param {HTMLElement} node
- * @param {import("./intersect.svelte.d.ts").IntersectActionOptions} [options]
- */
+import { fromAction } from "svelte/attachments";
+
 export function intersect(node, options = {}) {
   let {
     root = null,
@@ -14,29 +9,30 @@ export function intersect(node, options = {}) {
     skip = false,
   } = options;
 
-  /** @type {IntersectionObserver} */
   let observer;
 
-  const createObserver = () =>
-    new IntersectionObserver(
+  const createObserver = () => {
+    if (typeof IntersectionObserver === "undefined") return null;
+
+    return new IntersectionObserver(
       (entries) => {
         for (const entry of entries) {
           node.dispatchEvent(new CustomEvent("observe", { detail: entry }));
 
           if (entry.isIntersecting) {
             node.dispatchEvent(new CustomEvent("intersect", { detail: entry }));
-            if (once) observer.unobserve(node);
+            if (once) observer?.unobserve(node);
           }
         }
       },
       { root, rootMargin, threshold },
     );
+  };
 
   observer = createObserver();
-  if (!skip) observer.observe(node);
+  if (!skip) observer?.observe(node);
 
   return {
-    /** @param {import("./intersect.svelte.d.ts").IntersectActionOptions} [newOptions] */
     update(newOptions = {}) {
       once = newOptions.once ?? false;
 
@@ -52,18 +48,80 @@ export function intersect(node, options = {}) {
         rootMargin = newOptions.rootMargin ?? "0px";
         threshold = newOptions.threshold ?? 0;
 
-        observer.disconnect();
+        observer?.disconnect();
         observer = createObserver();
-        if (!newSkip) observer.observe(node);
+        if (!newSkip) observer?.observe(node);
       } else if (newSkip !== skip) {
-        if (newSkip) observer.unobserve(node);
-        else observer.observe(node);
+        if (newSkip) observer?.unobserve(node);
+        else observer?.observe(node);
       }
 
       skip = newSkip;
     },
     destroy() {
-      observer.disconnect();
+      observer?.disconnect();
     },
   };
 }
+
+export function intersectAttachment(getOptions = () => ({})) {
+  return fromAction(intersect, getOptions);
+}
+
+export function createIntersectionGroup(getSharedOptions = () => ({})) {
+  let observer;
+
+  const callbacks = new Map();
+
+  const handleEntries = (
+ entries,
+  ) => {
+    for (const entry of entries) {
+      const target = entry.target;
+      const nodeOptions = callbacks.get(target);
+
+      nodeOptions?.onobserve?.(entry);
+
+      if (entry.isIntersecting) {
+        nodeOptions?.onintersect?.(
+ (
+            entry
+          ),
+        );
+        if (nodeOptions?.once) observer?.unobserve(target);
+      }
+    }
+  };
+
+  function attach(nodeOptions = {}) {
+    return ( node) => {
+      if (!observer && typeof IntersectionObserver !== "undefined") {
+        const {
+          root = null,
+          rootMargin = "0px",
+          threshold = 0,
+        } = getSharedOptions();
+        observer = new IntersectionObserver(handleEntries, {
+          root,
+          rootMargin,
+          threshold,
+        });
+      }
+
+      callbacks.set(node, nodeOptions);
+      if (!nodeOptions.skip) observer?.observe(node);
+
+      return () => {
+        observer?.unobserve(node);
+        callbacks.delete(node);
+
+        if (callbacks.size === 0) {
+          observer?.disconnect();
+          observer = undefined;
+        }
+      };
+    };
+  }
+
+  return { attach };
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "svelte-intersection-observer",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "license": "MIT",
-  "description": "Detect if an element is in the viewport using the Intersection Observer API",
+  "description": "Detects when an element enters or exits the viewport using the Intersection Observer API.",
   "author": "Eric Liu (https://github.com/metonym)",
   "type": "module",
   "svelte": "./index.js",