rune-scroller 2.1.1 → 2.2.2

package/README.md

@@ -1,8 +1,4 @@
-# ⚡ Rune Scroller - Full Reference
-
-**📚 Complete API Reference** — Detailed documentation for all features and options.
-
----
+# ⚡ Rune Scroller
 
 <div align="center">
 	<img src="./logo.png" alt="Rune Scroller Logo" width="200" />
@@ -26,16 +22,13 @@
 
 ## ✨ Features
 
-- **12.7KB gzipped** (40.3KB uncompressed) - Minimal overhead, optimized for production
+- **5.7KB gzipped** (JS+CSS) - Minimal overhead
 - **Zero dependencies** - Pure Svelte 5 + IntersectionObserver
-- **14 animations** - Fade, Zoom, Flip, Slide, Bounce variants
-- **Full TypeScript support** - Type definitions generated from JSDoc
+- **14 animations** - Fade, Zoom, Flip, Slide, Bounce
+- **TypeScript support** - Full type definitions
 - **SSR-ready** - SvelteKit compatible
 - **GPU-accelerated** - Pure CSS transforms
 - **Accessible** - Respects `prefers-reduced-motion`
-- **v2.0.0 New** - `onVisible` callback, ResizeObserver support, animation validation, sentinel customization
-- **✨ Latest** - `useIntersection` migrated to Svelte 5 `$effect` rune for better lifecycle management
-- **🚀 Bundle optimized** - CSS with custom properties, production build minification
 
 ---
 
@@ -43,47 +36,15 @@
 
 ```bash
 npm install rune-scroller
-# or
-pnpm add rune-scroller
-# or
-yarn add rune-scroller
 ```
 
 ---
 
 ## 🚀 Quick Start
 
-### Step 1: Import CSS (required)
-
-**⚠️ Important:** You must import the CSS file once in your app.
-
-**Option A - In your root layout (recommended for SvelteKit):**
-
-```svelte
-<!-- src/routes/+layout.svelte -->
-<script>
-	import 'rune-scroller/animations.css';
-	let { children } = $props();
-</script>
-
-{@render children()}
-```
-
-**Option B - In each component that uses animations:**
-
-```svelte
-<script>
-	import runeScroller from 'rune-scroller';
-	import 'rune-scroller/animations.css';
-</script>
-```
-
-### Step 2: Use the animations
-
 ```svelte
 <script>
 	import runeScroller from 'rune-scroller';
-	// CSS already imported in layout or above
 </script>
 
 <!-- Simple animation -->
@@ -107,6 +68,7 @@ yarn add rune-scroller
 ## 🎨 Available Animations
 
 ### Fade (5)
+
 - `fade-in` - Simple opacity fade
 - `fade-in-up` - Fade + move up 300px
 - `fade-in-down` - Fade + move down 300px
@@ -114,6 +76,7 @@ yarn add rune-scroller
 - `fade-in-right` - Fade + move from left 300px
 
 ### Zoom (5)
+
 - `zoom-in` - Scale from 0.3 to 1
 - `zoom-out` - Scale from 2 to 1
 - `zoom-in-up` - Zoom (0.5→1) + move up 300px
@@ -121,6 +84,7 @@ yarn add rune-scroller
 - `zoom-in-right` - Zoom (0.5→1) + move from left 300px
 
 ### Others (4)
+
 - `flip` - 3D flip on Y-axis
 - `flip-x` - 3D flip on X-axis
 - `slide-rotate` - Slide + rotate 10°
@@ -132,114 +96,45 @@ yarn add rune-scroller
 
 ```typescript
 interface RuneScrollerOptions {
-	animation?: AnimationType;  // Animation name (default: 'fade-in')
-	duration?: number;          // Duration in ms (default: 800)
-	repeat?: boolean;           // Repeat on scroll (default: false)
-	debug?: boolean;            // Show sentinel as visible line (default: false)
-	offset?: number;            // Sentinel offset in px (default: 0, negative = above)
-	onVisible?: (element: HTMLElement) => void;  // Callback when animation triggers (v2.0.0+)
-	sentinelColor?: string;     // Sentinel debug color, e.g. '#ff6b6b' (v2.0.0+)
-	sentinelId?: string;        // Custom ID for sentinel identification (v2.0.0+)
+  animation?: AnimationType // Animation name (default: 'fade-in')
+  duration?: number // Duration in ms (default: 800)
+  repeat?: boolean // Repeat on scroll (default: false)
+  debug?: boolean // Show sentinel as visible line (default: false)
+  offset?: number // Sentinel offset in px (default: 0, negative = earlier)
+  onVisible?: (element: HTMLElement) => void // Callback when visible
+  sentinelColor?: string // Debug sentinel color (e.g. '#ff6b6b')
+  sentinelId?: string // Custom sentinel ID
 }
 ```
 
-### Option Details
-
-- **`animation`** - Type of animation to play. Choose from 14 built-in animations listed above. Invalid animations automatically fallback to 'fade-in' with a console warning.
-- **`duration`** - How long the animation lasts in milliseconds (default: 800ms).
-- **`repeat`** - If `true`, animation plays every time sentinel enters viewport. If `false`, plays only once.
-- **`debug`** - If `true`, displays the sentinel element as a visible line below your element. Useful for seeing exactly when animations trigger. Default color is cyan (#00e0ff), customize with `sentinelColor`.
-- **`offset`** - Offset of the sentinel in pixels. Positive values move sentinel down (delays animation), negative values move it up (triggers earlier). Useful for large elements where you want animation to trigger before the entire element is visible.
-- **`onVisible`** *(v2.0.0+)* - Callback function triggered when the animation becomes visible. Receives the animated element as parameter. Useful for analytics, lazy loading, or triggering custom effects.
-- **`sentinelColor`** *(v2.0.0+)* - Customize the debug sentinel color (e.g., '#ff6b6b' for red). Only visible when `debug: true`. Useful for distinguishing multiple sentinels on the same page.
-- **`sentinelId`** *(v2.0.0+)* - Set a custom ID for the sentinel element. If not provided, an auto-ID is generated (`sentinel-1`, `sentinel-2`, etc.). Useful for identifying sentinels in DevTools and tracking which element owns which sentinel.
-
 ### Examples
 
 ```svelte
 <!-- Basic -->
-<div use:runeScroller={{ animation: 'zoom-in' }}>
-	Content
-</div>
+<div use:runeScroller={{ animation: 'zoom-in' }}>Content</div>
 
 <!-- Custom duration -->
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>
-	Fast animation
-</div>
+<div use:runeScroller={{ animation: 'fade-in-up', duration: 1000 }}>Fast</div>
 
 <!-- Repeat mode -->
-<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>
-	Repeats every time you scroll
-</div>
-
-<!-- Debug mode - shows cyan line marking sentinel position -->
-<div use:runeScroller={{ animation: 'fade-in', debug: true }}>
-	The cyan line below this shows when animation will trigger
-</div>
-
-<!-- Multiple options -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	duration: 1200,
-	repeat: true,
-	debug: true
-}}>
-	Full featured example
-</div>
+<div use:runeScroller={{ animation: 'bounce-in', repeat: true }}>Repeats</div>
 
-<!-- Large element - trigger animation earlier with negative offset -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	offset: -200  // Trigger 200px before element bottom
-}}>
-	Large content that needs early triggering
-</div>
+<!-- Debug mode -->
+<div use:runeScroller={{ animation: 'fade-in', debug: true }}>Debug</div>
 
-<!-- Delay animation by moving sentinel down -->
-<div use:runeScroller={{
-	animation: 'zoom-in',
-	offset: 300  // Trigger 300px after element bottom
-}}>
-	Content with delayed animation
+<!-- Trigger earlier with negative offset -->
+<div use:runeScroller={{ animation: 'fade-in-up', offset: -200 }}>
+	Triggers 200px before element bottom
 </div>
 
-<!-- v2.0.0: onVisible callback for analytics tracking -->
+<!-- onVisible callback for analytics -->
 <div use:runeScroller={{
 	animation: 'fade-in-up',
 	onVisible: (el) => {
-		console.log('Animation visible!', el);
-		// Track analytics, load images, trigger API calls, etc.
-		window.gtag?.('event', 'animation_visible', { element: el.id });
+		window.gtag?.('event', 'section_viewed', { id: el.id });
 	}
 }}>
-	Tracked animation
-</div>
-
-<!-- v2.0.0: Custom sentinel color for debugging -->
-<div use:runeScroller={{
-	animation: 'fade-in',
-	debug: true,
-	sentinelColor: '#ff6b6b'  // Red instead of default cyan
-}}>
-	Red debug sentinel
-</div>
-
-<!-- v2.0.0: Custom sentinel ID for identification -->
-<div use:runeScroller={{
-	animation: 'zoom-in',
-	sentinelId: 'hero-zoom',
-	debug: true
-}}>
-	Identified sentinel (shows "hero-zoom" in debug mode)
-</div>
-
-<!-- v2.0.0: Auto-ID (sentinel-1, sentinel-2, etc) -->
-<div use:runeScroller={{
-	animation: 'fade-in-up',
-	debug: true
-	// sentinelId omitted → auto generates "sentinel-1", "sentinel-2", etc
-}}>
-	Auto-identified sentinel
+	Tracked section
 </div>
 ```
 
@@ -247,58 +142,36 @@ interface RuneScrollerOptions {
 
 ## 🎯 How It Works
 
-Rune Scroller uses **sentinel-based triggering**:
+**Sentinel-based triggering:**
 
-1. An invisible 1px sentinel element is created below your element
-2. When the sentinel enters the viewport, animation triggers
-3. This ensures precise timing regardless of element size
-4. Uses native IntersectionObserver for performance
-5. Pure CSS animations (GPU-accelerated)
-6. *(v2.0.0)* Sentinel automatically repositions on element resize via ResizeObserver
+1. Invisible 1px sentinel created below your element
+2. When sentinel enters viewport, animation triggers
+3. Uses native IntersectionObserver for performance
+4. Pure CSS animations (GPU-accelerated)
+5. ResizeObserver auto-repositions sentinel
 
 **Why sentinels?**
+
 - Accurate timing across all screen sizes
 - No complex offset calculations
-- Handles staggered animations naturally
-- Sentinel stays fixed while element animates (no observer confusion with transforms)
-
-**Automatic ResizeObserver** *(v2.0.0+)*
-- Sentinel repositions automatically when element resizes
-- Works with responsive layouts and dynamic content
-- No configuration needed—it just works
+- Works with animated elements (transforms don't affect observer)
 
 ---
 
 ## 🌐 SSR Compatibility
 
-Works seamlessly with SvelteKit. Import CSS in your root layout:
+Works seamlessly with SvelteKit:
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script>
-	import 'rune-scroller/animations.css';
+	import runeScroller from 'rune-scroller';
 	let { children } = $props();
 </script>
 
 {@render children()}
 ```
 
-Then use animations anywhere in your app:
-
-```svelte
-<!-- src/routes/+page.svelte -->
-<script>
-	import runeScroller from 'rune-scroller';
-</script>
-
-<!-- No special handling needed -->
-<div use:runeScroller={{ animation: 'fade-in-up' }}>
-	Works in SvelteKit SSR!
-</div>
-```
-
-The library checks for browser environment and gracefully handles server-side rendering.
-
 ---
 
 ## ♿ Accessibility
@@ -306,73 +179,32 @@ The library checks for browser environment and gracefully handles server-side re
 Respects `prefers-reduced-motion`:
 
 ```css
-/* In animations.css */
 @media (prefers-reduced-motion: reduce) {
-	.scroll-animate {
-		animation: none !important;
-		opacity: 1 !important;
-		transform: none !important;
-	}
+  .scroll-animate {
+    animation: none !important;
+    opacity: 1 !important;
+    transform: none !important;
+  }
 }
 ```
 
-Users who prefer reduced motion will see content without animations.
-
 ---
 
 ## 📚 API Reference
-### Public API
-
-Rune Scroller exports a **single action-based API** (no components):
-
-1. **`runeScroller`** (default) - Sentinel-based, simple, powerful
-
-**Why actions instead of components?**
-- Actions are lightweight directives
-- No DOM wrapper overhead
-- Better performance
-- More flexible
-
-### Main Export
 
 ```typescript
 // Default export
-import runeScroller from 'rune-scroller';
+import runeScroller from "rune-scroller"
 
 // Named exports
 import {
-	useIntersection,            // Composable
-	useIntersectionOnce,        // Composable
-	calculateRootMargin         // Utility
-} from 'rune-scroller';
+  useIntersection, // Composable
+  useIntersectionOnce, // Composable
+  calculateRootMargin, // Utility
+} from "rune-scroller"
 
 // Types
-import type {
-	AnimationType,
-	RuneScrollerOptions,
-	IntersectionOptions,
-	UseIntersectionReturn
-} from 'rune-scroller';
-```
-
-### TypeScript Types
-
-```typescript
-type AnimationType =
-	| 'fade-in' | 'fade-in-up' | 'fade-in-down' | 'fade-in-left' | 'fade-in-right'
-	| 'zoom-in' | 'zoom-out' | 'zoom-in-up' | 'zoom-in-left' | 'zoom-in-right'
-	| 'flip' | 'flip-x' | 'slide-rotate' | 'bounce-in';
-
-interface RuneScrollerOptions {
-	animation?: AnimationType;
-	duration?: number;
-	repeat?: boolean;
-	debug?: boolean;
-	offset?: number;
-	onVisible?: (element: HTMLElement) => void;      // v2.0.0+
-	sentinelColor?: string;                          // v2.0.0+
-	sentinelId?: string;                             // v2.0.0+
-}
+import type { AnimationType, RuneScrollerOptions } from "rune-scroller"
 ```
 
 ---
@@ -384,46 +216,33 @@ interface RuneScrollerOptions {
 ```svelte
 <script>
 	import runeScroller from 'rune-scroller';
-	import 'rune-scroller/animations.css';
-
-	const items = [
-		{ title: 'Feature 1', description: 'Description 1' },
-		{ title: 'Feature 2', description: 'Description 2' },
-		{ title: 'Feature 3', description: 'Description 3' }
-	];
+	const items = ['Item 1', 'Item 2', 'Item 3'];
 </script>
 
-<div class="grid">
-	{#each items as item}
-		<div use:runeScroller={{ animation: 'fade-in-up', duration: 800 }}>
-			<h3>{item.title}</h3>
-			<p>{item.description}</p>
-		</div>
-	{/each}
-</div>
+{#each items as item, i}
+	<div use:runeScroller={{
+		animation: 'fade-in-up',
+		duration: 800,
+		style: `--delay: ${i * 100}ms`
+	}}>
+		{item}
+	</div>
+{/each}
 ```
 
 ### Hero Section
 
 ```svelte
-<div use:runeScroller={{ animation: 'fade-in-down', duration: 1000 }}>
-	<h1>Welcome</h1>
-</div>
-
-<div use:runeScroller={{ animation: 'fade-in-up', duration: 1200 }}>
-	<p>Engaging content</p>
-</div>
-
-<div use:runeScroller={{ animation: 'zoom-in', duration: 1000 }}>
-	<button>Get Started</button>
-</div>
+<h1 use:runeScroller={{ animation: 'fade-in-down', duration: 1000 }}>Welcome</h1>
+<p use:runeScroller={{ animation: 'fade-in-up', duration: 1200 }}>Subtitle</p>
+<button use:runeScroller={{ animation: 'zoom-in', duration: 800 }}>Get Started</button>
 ```
 
 ---
 
 ## 🔗 Links
 
-- **npm Package**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)
+- **npm**: [rune-scroller](https://www.npmjs.com/package/rune-scroller)
 - **GitHub**: [lelabdev/rune-scroller](https://github.com/lelabdev/rune-scroller)
 - **Changelog**: [CHANGELOG.md](https://github.com/lelabdev/rune-scroller/blob/main/lib/CHANGELOG.md)
 
@@ -435,18 +254,4 @@ MIT © [ludoloops](https://github.com/ludoloops)
 
 ---
 
-## 🤝 Contributing
-
-Contributions welcome! Please open an issue or PR on GitHub.
-
-```bash
-# Development
-bun install
-bun run dev
-bun test
-bun run build
-```
-
----
-
 Made with ❤️ by [LeLab.dev](https://lelab.dev)

package/dist/dom-utils.d.ts

@@ -24,6 +24,7 @@ export function createSentinel(element: HTMLElement, debug?: boolean, offset?: n
 };
 /**
  * Check if CSS animations are loaded and warn if not (dev only)
+ * Uses cache to avoid expensive getComputedStyle() on every element creation
  * @returns {boolean} True if CSS appears to be loaded
  */
 export function checkAndWarnIfCSSNotLoaded(): boolean;

package/dist/dom-utils.js

@@ -4,6 +4,13 @@
  */
 let sentinelCounter = 0;
 
+/**
+ * Cache to check CSS only once per page load
+ * Avoids expensive getComputedStyle() calls
+ * @type {boolean | null}
+ */
+let cssCheckResult = null;
+
 /**
  * @param {HTMLElement} element
  * @param {number} [duration]
@@ -38,7 +45,7 @@ export function createSentinel(element, debug = false, offset = 0, sentinelColor
 	const sentinel = document.createElement('div');
 	// Use offsetHeight instead of getBoundingClientRect for accurate dimensions
 	// getBoundingClientRect returns transformed dimensions (affected by scale, etc)
-	// offsetHeight returns the actual element height independent of CSS transforms
+	// offsetHeight returns actual element height independent of CSS transforms
 	const elementHeight = element.offsetHeight;
 	const sentinelTop = elementHeight + offset;
 
@@ -48,7 +55,7 @@ export function createSentinel(element, debug = false, offset = 0, sentinelColor
 		sentinelId = `sentinel-${sentinelCounter}`;
 	}
 
-	// Always set the data-sentinel-id attribute
+	// Always set to data-sentinel-id attribute
 	sentinel.setAttribute('data-sentinel-id', sentinelId);
 
 	if (debug) {
@@ -71,11 +78,15 @@ export function createSentinel(element, debug = false, offset = 0, sentinelColor
 
 /**
  * Check if CSS animations are loaded and warn if not (dev only)
+ * Uses cache to avoid expensive getComputedStyle() on every element creation
  * @returns {boolean} True if CSS appears to be loaded
  */
 export function checkAndWarnIfCSSNotLoaded() {
-	if (typeof document === 'undefined') return;
-	if (process.env.NODE_ENV === 'production') return;
+	if (typeof document === 'undefined') return false;
+	if (process.env.NODE_ENV === 'production') return true;
+
+	// Return cached result if already checked (avoids expensive reflows)
+	if (cssCheckResult !== null) return cssCheckResult;
 
 	// Try to detect if animations.css is loaded by checking for animation classes
 	const test = document.createElement('div');
@@ -94,4 +105,8 @@ export function checkAndWarnIfCSSNotLoaded() {
 			'Documentation: https://github.com/lelabdev/rune-scroller#installation'
 		);
 	}
+
+	// Cache the result for future calls
+	cssCheckResult = hasAnimation;
+	return hasAnimation;
 }

package/dist/index.js

@@ -6,6 +6,9 @@
  * @module rune-scroller
  */
 
+// Import CSS animations automatically
+import './animations.css';
+
 // Main action (default export - recommended)
 import { runeScroller } from './runeScroller.js';
 export default runeScroller;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rune-scroller",
-  "version": "2.1.1",
-  "description": "Lightweight, high-performance scroll animations for Svelte 5. 12.7KB gzipped, zero dependencies.",
+  "version": "2.2.2",
+  "description": "Lightweight, high-performance scroll animations for Svelte 5. 14KB gzipped, zero dependencies.",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",