@ariefsn/svelte-sentinel 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arief Setiyo Nugroho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# Svelte Sentinel
+
+![svelte-sentinel feature banner](./static/feature.svg)
+
+[![npm](https://img.shields.io/npm/v/@ariefsn/svelte-sentinel?color=ff3e00&logo=npm)](https://www.npmjs.com/package/@ariefsn/svelte-sentinel)
+[![GitHub](https://img.shields.io/badge/GitHub-ariefsn%2Fsvelte--sentinel-181717?logo=github)](https://github.com/ariefsn/svelte-sentinel)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE.md)
+
+A lightweight **Svelte 5** component that wraps the browser's [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) API, letting you declaratively respond to an element entering or leaving the viewport.
+
+- Zero external dependencies
+- Svelte 5 runes (`$props`, `$state`, `$bindable`)
+- Full TypeScript support
+- Callbacks, bindable state, and conditional snippet slots
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @ariefsn/svelte-sentinel
+
+# pnpm
+pnpm add @ariefsn/svelte-sentinel
+
+# yarn
+yarn add @ariefsn/svelte-sentinel
+
+# bun
+bun add @ariefsn/svelte-sentinel
+```
+
+**Peer dependency:** Svelte 5 (`^5.0.0`)
+
+---
+
+## Quick Start
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+</script>
+
+<Sentinel onEnter={() => console.log('in view!')} onExit={() => console.log('out of view!')}>
+  <p>Watch me scroll!</p>
+</Sentinel>
+```
+
+---
+
+## Usage
+
+### Basic visibility callbacks
+
+Use `onEnter`, `onExit`, or `onViewChange` to react to visibility changes.
+Each callback receives the raw [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) for full control.
+
+```svelte
+<Sentinel
+  onEnter={(entry) => console.log('entered', entry.intersectionRatio)}
+  onExit={() => console.log('exited')}
+  onViewChange={(isVisible) => console.log('visible:', isVisible)}
+>
+  <div>Observed element</div>
+</Sentinel>
+```
+
+---
+
+### Reactive state with `bind:isVisible`
+
+Bind the `isVisible` prop to read the element's visibility reactively anywhere in the parent component — no callback needed.
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+
+  let visible = $state(false);
+</script>
+
+<header class:scrolled={!visible}>Sticky header</header>
+
+<Sentinel bind:isVisible={visible}>
+  <h1>Page hero</h1>
+</Sentinel>
+```
+
+---
+
+### Animate on scroll (one-shot with `once`)
+
+Set `once={true}` to disconnect the observer after the element becomes visible for the first time. Perfect for entrance animations that should only play once.
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+</script>
+
+<style>
+  .box { opacity: 0; transform: translateY(2rem); transition: opacity .5s, transform .5s; }
+  .box.visible { opacity: 1; transform: none; }
+</style>
+
+<Sentinel once>
+  {#snippet whenVisible()}
+    <div class="box visible">I animated in!</div>
+  {/snippet}
+  {#snippet whenHidden()}
+    <div class="box">Waiting…</div>
+  {/snippet}
+</Sentinel>
+```
+
+---
+
+### Conditional content with `whenVisible` / `whenHidden`
+
+Use the `whenVisible` and `whenHidden` snippet slots to declaratively swap content based on viewport position. No state management required in the parent.
+
+```svelte
+<Sentinel>
+  {#snippet whenVisible()}
+    <span class="badge green">In view</span>
+  {/snippet}
+  {#snippet whenHidden()}
+    <span class="badge grey">Out of view</span>
+  {/snippet}
+</Sentinel>
+```
+
+> **Note:** `children` is always rendered and is independent of `whenVisible` / `whenHidden`. Use `children` for static content that should always be inside the wrapper.
+
+---
+
+### Lazy loading with `rootMargin`
+
+`rootMargin` expands the detection area beyond the viewport — useful for pre-loading images or data before they scroll into view.
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+  let loaded = $state(false);
+</script>
+
+<!-- Start loading 300px before the image enters the viewport -->
+<Sentinel rootMargin="300px" once onEnter={() => (loaded = true)}>
+  {#if loaded}
+    <img src="/photo.jpg" alt="Lazy loaded" />
+  {:else}
+    <div class="placeholder">Loading…</div>
+  {/if}
+</Sentinel>
+```
+
+---
+
+### Custom scroll container with `root`
+
+Observe visibility inside a scrollable container instead of the browser viewport.
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+  let container: HTMLElement;
+</script>
+
+<div bind:this={container} style="overflow-y: scroll; height: 400px;">
+  <Sentinel root={container} onEnter={() => console.log('visible inside container')}>
+    <div style="margin-top: 600px;">Deep content</div>
+  </Sentinel>
+</div>
+```
+
+---
+
+### Custom wrapper tag with `as`
+
+Change the wrapper element's HTML tag to fit your semantic HTML.
+
+```svelte
+<Sentinel as="section" class="hero-section" onEnter={handleEnter}>
+  <h1>Hero Section</h1>
+</Sentinel>
+
+<!-- Renders as: <section class="hero-section">…</section> -->
+```
+
+---
+
+### Infinite scroll
+
+Use a small invisible sentinel at the end of a list to trigger loading the next page.
+
+```svelte
+<script>
+  import { Sentinel } from '@ariefsn/svelte-sentinel';
+
+  let items = $state(Array.from({ length: 20 }, (_, i) => i + 1));
+  let loading = $state(false);
+
+  async function loadMore() {
+    if (loading) return;
+    loading = true;
+    await new Promise((r) => setTimeout(r, 500)); // simulate fetch
+    items = [...items, ...Array.from({ length: 20 }, (_, i) => items.length + i + 1)];
+    loading = false;
+  }
+</script>
+
+<ul>
+  {#each items as item}
+    <li>{item}</li>
+  {/each}
+</ul>
+
+{#if loading}
+  <p>Loading…</p>
+{/if}
+
+<!-- Invisible sentinel at the bottom of the list -->
+<Sentinel onEnter={loadMore} />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | auto-generated | `id` attribute on the wrapper element. |
+| `class` | `string` | `undefined` | CSS class(es) for the wrapper element. |
+| `as` | `string` | `'div'` | HTML tag for the wrapper element (e.g. `'section'`, `'li'`). |
+| `threshold` | `number \| number[]` | `0` | When to trigger: `0` = any pixel visible, `1` = fully visible, or an array of ratios. |
+| `rootMargin` | `string` | `'0px'` | CSS margin around the root. Positive values expand, negative values shrink the detection area. |
+| `root` | `Element \| Document \| null` | `null` | Scroll container to use instead of the browser viewport. |
+| `once` | `boolean` | `false` | Disconnect the observer after the element first becomes visible. |
+| `isVisible` | `boolean` | `false` | Bindable. Use `bind:isVisible` to reactively track visibility. |
+| `onEnter` | `(entry: IntersectionObserverEntry) => void` | — | Called when the element enters the viewport. |
+| `onExit` | `(entry: IntersectionObserverEntry) => void` | — | Called when the element exits the viewport. |
+| `onViewChange` | `(isVisible: boolean, entry: IntersectionObserverEntry) => void` | — | Called on every visibility change. |
+| `children` | `Snippet` | — | Always-rendered content inside the wrapper. |
+| `whenVisible` | `Snippet` | — | Rendered only while the element is visible. |
+| `whenHidden` | `Snippet` | — | Rendered only while the element is not visible. |
+
+---
+
+## TypeScript
+
+All types are exported from the package entry point.
+
+```ts
+import type { SentinelProps } from '@ariefsn/svelte-sentinel';
+```
+
+---
+
+## Developing
+
+```bash
+# Install dependencies
+bun install
+
+# Start the dev server (runs the demo app)
+bun run dev
+
+# Run tests
+bun run test
+
+# Type-check
+bun run check
+
+# Build the library
+bun run prepack
+```
+
+---
+
+## License
+
+[MIT](./LICENSE.md) © [ariefsn](https://github.com/ariefsn)
+
+---
+
+[GitHub](https://github.com/ariefsn/svelte-sentinel) · [npm](https://www.npmjs.com/package/@ariefsn/svelte-sentinel)

package/dist/components/Sentinel.svelte

@@ -0,0 +1,182 @@
+<script lang="ts">
+	import { onMount, type Snippet } from 'svelte';
+
+	/**
+	 * Props for the Sentinel component.
+	 *
+	 * Sentinel wraps the browser's `IntersectionObserver` API into a reactive
+	 * Svelte 5 component, letting you declaratively respond to an element
+	 * entering or leaving the viewport (or a custom scroll container).
+	 */
+	export type SentinelProps = {
+		/**
+		 * Unique `id` for the wrapper element.
+		 * If omitted, a random ID is auto-generated.
+		 */
+		id?: string;
+
+		/**
+		 * CSS class(es) to apply to the wrapper element.
+		 */
+		class?: string;
+
+		/**
+		 * HTML tag to use as the wrapper element.
+		 * @default 'div'
+		 * @example 'section' | 'article' | 'span' | 'li'
+		 */
+		as?: string;
+
+		/**
+		 * Called when the element **enters** the viewport (or root).
+		 * Receives the raw `IntersectionObserverEntry` for advanced usage
+		 * (e.g. reading `intersectionRatio`).
+		 */
+		onEnter?: (entry: IntersectionObserverEntry) => void;
+
+		/**
+		 * Called when the element **exits** the viewport (or root).
+		 * Receives the raw `IntersectionObserverEntry`.
+		 */
+		onExit?: (entry: IntersectionObserverEntry) => void;
+
+		/**
+		 * Called whenever the element's visibility changes (enter **or** exit).
+		 * @param isVisible - `true` if entering, `false` if exiting.
+		 * @param entry - The raw `IntersectionObserverEntry`.
+		 */
+		onViewChange?: (isVisible: boolean, entry: IntersectionObserverEntry) => void;
+
+		/**
+		 * `IntersectionObserver` threshold(s). A number or array of numbers
+		 * between `0` and `1`.
+		 * - `0` — fires as soon as **any** pixel is visible (default).
+		 * - `1` — fires only when the element is **fully** visible.
+		 * - `[0, 0.5, 1]` — fires at 0 %, 50 %, and 100 % visibility.
+		 * @default 0
+		 */
+		threshold?: number | number[];
+
+		/**
+		 * Margin around the root element, using CSS shorthand syntax
+		 * (e.g. `'100px 0px'`).
+		 * - Positive values **expand** the detection area (useful for
+		 *   pre-loading content before it scrolls into view).
+		 * - Negative values **shrink** the detection area.
+		 * @default '0px'
+		 */
+		rootMargin?: string;
+
+		/**
+		 * The element used as the intersection viewport.
+		 * - Set to a scrollable container element to observe visibility
+		 *   within that container instead of the browser viewport.
+		 * - `null` uses the browser viewport.
+		 * @default null
+		 */
+		root?: Element | Document | null;
+
+		/**
+		 * When `true`, the observer automatically disconnects after the
+		 * element becomes visible for the **first time**. Ideal for
+		 * one-time animations or lazy-loading.
+		 * @default false
+		 */
+		once?: boolean;
+
+		/**
+		 * Reactive flag indicating whether the element is currently visible.
+		 * Use `bind:isVisible` on the parent to read this value reactively
+		 * without needing a callback.
+		 * @default false
+		 */
+		isVisible?: boolean;
+
+		/**
+		 * Content that is **always** rendered inside the sentinel wrapper,
+		 * regardless of visibility.
+		 */
+		children?: Snippet;
+
+		/**
+		 * Content rendered **only while the element is visible**.
+		 * Swaps with `whenHidden` as the element enters/exits the viewport.
+		 */
+		whenVisible?: Snippet;
+
+		/**
+		 * Content rendered **only while the element is not visible**.
+		 * Swaps with `whenVisible` as the element enters/exits the viewport.
+		 */
+		whenHidden?: Snippet;
+	};
+
+	let {
+		id,
+		class: className,
+		as: tag = 'div',
+		onEnter,
+		onExit,
+		onViewChange,
+		threshold = 0,
+		rootMargin = '0px',
+		root = null,
+		once = false,
+		isVisible = $bindable(false),
+		children,
+		whenVisible,
+		whenHidden
+	}: SentinelProps = $props();
+
+	let ref: Element | null = $state(null);
+
+	onMount(() => {
+		if (!ref) return;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				const entry = entries[0];
+				if (!entry) return;
+
+				const visible = entry.isIntersecting;
+				isVisible = visible;
+				onViewChange?.(visible, entry);
+
+				if (visible) {
+					onEnter?.(entry);
+					if (once) observer.disconnect();
+				} else {
+					onExit?.(entry);
+				}
+			},
+			{ threshold, rootMargin, root }
+		);
+
+		observer.observe(ref);
+		return () => observer.disconnect();
+	});
+</script>
+
+<!--
+  @component
+  **Sentinel** — a lightweight Svelte 5 wrapper around `IntersectionObserver`.
+
+  Detects when the wrapped element enters or exits the viewport and exposes
+  callbacks, a bindable `isVisible` flag, and conditional snippet slots
+  (`whenVisible` / `whenHidden`).
+
+  @example
+  ```svelte
+  <Sentinel onEnter={() => console.log('visible!')} onExit={() => console.log('hidden!')}>
+    <p>Watch me scroll!</p>
+  </Sentinel>
+  ```
+-->
+<svelte:element this={tag} {id} class={className} bind:this={ref}>
+	{@render children?.()}
+	{#if isVisible}
+		{@render whenVisible?.()}
+	{:else}
+		{@render whenHidden?.()}
+	{/if}
+</svelte:element>

package/dist/components/Sentinel.svelte.d.ts

@@ -0,0 +1,114 @@
+import { type Snippet } from 'svelte';
+/**
+ * Props for the Sentinel component.
+ *
+ * Sentinel wraps the browser's `IntersectionObserver` API into a reactive
+ * Svelte 5 component, letting you declaratively respond to an element
+ * entering or leaving the viewport (or a custom scroll container).
+ */
+export type SentinelProps = {
+    /**
+     * Unique `id` for the wrapper element.
+     * If omitted, a random ID is auto-generated.
+     */
+    id?: string;
+    /**
+     * CSS class(es) to apply to the wrapper element.
+     */
+    class?: string;
+    /**
+     * HTML tag to use as the wrapper element.
+     * @default 'div'
+     * @example 'section' | 'article' | 'span' | 'li'
+     */
+    as?: string;
+    /**
+     * Called when the element **enters** the viewport (or root).
+     * Receives the raw `IntersectionObserverEntry` for advanced usage
+     * (e.g. reading `intersectionRatio`).
+     */
+    onEnter?: (entry: IntersectionObserverEntry) => void;
+    /**
+     * Called when the element **exits** the viewport (or root).
+     * Receives the raw `IntersectionObserverEntry`.
+     */
+    onExit?: (entry: IntersectionObserverEntry) => void;
+    /**
+     * Called whenever the element's visibility changes (enter **or** exit).
+     * @param isVisible - `true` if entering, `false` if exiting.
+     * @param entry - The raw `IntersectionObserverEntry`.
+     */
+    onViewChange?: (isVisible: boolean, entry: IntersectionObserverEntry) => void;
+    /**
+     * `IntersectionObserver` threshold(s). A number or array of numbers
+     * between `0` and `1`.
+     * - `0` — fires as soon as **any** pixel is visible (default).
+     * - `1` — fires only when the element is **fully** visible.
+     * - `[0, 0.5, 1]` — fires at 0 %, 50 %, and 100 % visibility.
+     * @default 0
+     */
+    threshold?: number | number[];
+    /**
+     * Margin around the root element, using CSS shorthand syntax
+     * (e.g. `'100px 0px'`).
+     * - Positive values **expand** the detection area (useful for
+     *   pre-loading content before it scrolls into view).
+     * - Negative values **shrink** the detection area.
+     * @default '0px'
+     */
+    rootMargin?: string;
+    /**
+     * The element used as the intersection viewport.
+     * - Set to a scrollable container element to observe visibility
+     *   within that container instead of the browser viewport.
+     * - `null` uses the browser viewport.
+     * @default null
+     */
+    root?: Element | Document | null;
+    /**
+     * When `true`, the observer automatically disconnects after the
+     * element becomes visible for the **first time**. Ideal for
+     * one-time animations or lazy-loading.
+     * @default false
+     */
+    once?: boolean;
+    /**
+     * Reactive flag indicating whether the element is currently visible.
+     * Use `bind:isVisible` on the parent to read this value reactively
+     * without needing a callback.
+     * @default false
+     */
+    isVisible?: boolean;
+    /**
+     * Content that is **always** rendered inside the sentinel wrapper,
+     * regardless of visibility.
+     */
+    children?: Snippet;
+    /**
+     * Content rendered **only while the element is visible**.
+     * Swaps with `whenHidden` as the element enters/exits the viewport.
+     */
+    whenVisible?: Snippet;
+    /**
+     * Content rendered **only while the element is not visible**.
+     * Swaps with `whenVisible` as the element enters/exits the viewport.
+     */
+    whenHidden?: Snippet;
+};
+/**
+ * **Sentinel** — a lightweight Svelte 5 wrapper around `IntersectionObserver`.
+ *
+ * Detects when the wrapped element enters or exits the viewport and exposes
+ * callbacks, a bindable `isVisible` flag, and conditional snippet slots
+ * (`whenVisible` / `whenHidden`).
+ *
+ * @example
+ * ```svelte
+ * <Sentinel onEnter={() => console.log('visible!')} onExit={() => console.log('hidden!')}>
+ *   <p>Watch me scroll!</p>
+ * </Sentinel>
+ * ```
+ */
+declare const Sentinel: import("svelte").Component<SentinelProps, {}, "isVisible">;
+type Sentinel = ReturnType<typeof Sentinel>;
+export default Sentinel;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Sentinel } from './components/Sentinel.svelte';
+export type { SentinelProps } from './components/Sentinel.svelte';

package/dist/index.js

@@ -0,0 +1 @@
+export { default as Sentinel } from './components/Sentinel.svelte';

package/package.json

@@ -0,0 +1,85 @@
+{
+	"name": "@ariefsn/svelte-sentinel",
+	"version": "1.0.0",
+	"description": "A lightweight Svelte 5 component that wraps IntersectionObserver for declarative viewport visibility detection.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ariefsn/svelte-sentinel.git"
+	},
+	"homepage": "https://github.com/ariefsn/svelte-sentinel#readme",
+	"bugs": {
+		"url": "https://github.com/ariefsn/svelte-sentinel/issues"
+	},
+	"main": "./dist/index.js",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && bun run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write .",
+		"test:unit": "vitest",
+		"test": "bun run test:unit -- --run"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@eslint/compat": "^2.0.2",
+		"@eslint/js": "^9.39.2",
+		"@sveltejs/adapter-auto": "^7.0.0",
+		"@sveltejs/kit": "^2.50.2",
+		"@sveltejs/package": "^2.5.7",
+		"@sveltejs/vite-plugin-svelte": "^6.2.4",
+		"@types/node": "^22",
+		"@vitest/browser-playwright": "^4.0.18",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.14.0",
+		"globals": "^17.3.0",
+		"playwright": "^1.58.1",
+		"prettier": "^3.8.1",
+		"prettier-plugin-svelte": "^3.4.1",
+		"publint": "^0.3.17",
+		"svelte": "^5.51.0",
+		"svelte-check": "^4.3.6",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.54.0",
+		"vite": "^7.3.1",
+		"vitest": "^4.0.18",
+		"vitest-browser-svelte": "^2.0.2"
+	},
+	"keywords": [
+		"svelte",
+		"svelte5",
+		"intersection-observer",
+		"visibility",
+		"viewport",
+		"scroll",
+		"lazy-load",
+		"animate-on-scroll",
+		"in-view",
+		"sentinel"
+	]
+}