rune-scroller 0.1.10 → 1.0.0

package/README.md

@@ -37,11 +37,37 @@ 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';
+</script>
+
+<slot />
+```
+
+**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 -->
 <div use:runeScroller={{ animation: 'fade-in' }}>
@@ -92,10 +118,19 @@ interface RuneScrollerOptions {
 	animation?: AnimationType;  // Animation name (default: 'fade-in')
 	duration?: number;          // Duration in ms (default: 2000)
 	repeat?: boolean;           // Repeat on scroll (default: false)
-	debug?: boolean;            // Show sentinel element (default: false)
+	debug?: boolean;            // Show sentinel as visible line (default: false)
+	offset?: number;            // Sentinel offset in px (default: 0, negative = above)
 }
 ```
 
+### Option Details
+
+- **`animation`** - Type of animation to play. Choose from 14 built-in animations listed above.
+- **`duration`** - How long the animation lasts in milliseconds (default: 2000ms).
+- **`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 cyan line below your element. Useful for seeing exactly when animations trigger.
+- **`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.
+
 ### Examples
 
 ```svelte
@@ -114,9 +149,35 @@ interface RuneScrollerOptions {
 	Repeats every time you scroll
 </div>
 
-<!-- Debug mode (shows invisible sentinel) -->
+<!-- Debug mode - shows cyan line marking sentinel position -->
 <div use:runeScroller={{ animation: 'fade-in', debug: true }}>
-	You'll see a cyan line (the sentinel trigger)
+	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>
+
+<!-- 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>
+
+<!-- Delay animation by moving sentinel down -->
+<div use:runeScroller={{
+	animation: 'zoom-in',
+	offset: 300  // Trigger 300px after element bottom
+}}>
+	Content with delayed animation
 </div>
 ```
 
@@ -194,14 +255,25 @@ Rune Scroller uses **sentinel-based triggering**:
 
 ## 🌐 SSR Compatibility
 
-Works seamlessly with SvelteKit:
+Works seamlessly with SvelteKit. Import CSS in your root layout:
 
 ```svelte
+<!-- src/routes/+layout.svelte -->
 <script>
-	import runeScroller from 'rune-scroller';
 	import 'rune-scroller/animations.css';
 </script>
 
+<slot />
+```
+
+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!
@@ -270,6 +342,7 @@ interface RuneScrollerOptions {
 	duration?: number;
 	repeat?: boolean;
 	debug?: boolean;
+	offset?: number;
 }
 
 interface AnimateOptions {

package/dist/animations.css

@@ -21,6 +21,16 @@
 /* Animation states - transform-specific initial states */
 /* (opacity: 0 is already set in .scroll-animate base class) */
 
+/* Fade In (no transform, just opacity) */
+[data-animation='fade-in'] {
+	/* No transform needed, uses base opacity: 0 from .scroll-animate */
+}
+
+[data-animation='fade-in'].is-visible {
+	/* Inherits opacity: 1 from .scroll-animate.is-visible */
+	transform: none;
+}
+
 /* Fade In Up */
 [data-animation='fade-in-up'] {
 	transform: translateY(300px);

package/dist/dom-utils.svelte.d.ts

@@ -14,9 +14,10 @@ export declare function setCSSVariables(element: HTMLElement, duration?: number,
 export declare function setupAnimationElement(element: HTMLElement, animation: AnimationType): void;
 /**
  * Create sentinel element for observer-based triggering
- * Positioned absolutely after element, stays fixed while element animates
- * @param element - Reference element (used to position sentinel at its bottom)
+ * Positioned absolutely relative to element (no layout impact)
+ * @param element - Reference element (used to position sentinel)
  * @param debug - If true, shows the sentinel as a visible line for debugging
+ * @param offset - Offset in pixels from element bottom (default: 0, negative = above element)
  * @returns The created sentinel element
  */
-export declare function createSentinel(element: HTMLElement, debug?: boolean): HTMLElement;
+export declare function createSentinel(element: HTMLElement, debug?: boolean, offset?: number): HTMLElement;

package/dist/dom-utils.svelte.js

@@ -21,26 +21,28 @@ export function setupAnimationElement(element, animation) {
 }
 /**
  * Create sentinel element for observer-based triggering
- * Positioned absolutely after element, stays fixed while element animates
- * @param element - Reference element (used to position sentinel at its bottom)
+ * Positioned absolutely relative to element (no layout impact)
+ * @param element - Reference element (used to position sentinel)
  * @param debug - If true, shows the sentinel as a visible line for debugging
+ * @param offset - Offset in pixels from element bottom (default: 0, negative = above element)
  * @returns The created sentinel element
  */
-export function createSentinel(element, debug = false) {
+export function createSentinel(element, debug = false, offset = 0) {
     const sentinel = document.createElement('div');
-    // Get element dimensions to position sentinel at its bottom
+    // Get element dimensions to position sentinel at its bottom + offset
     const rect = element.getBoundingClientRect();
     const elementHeight = rect.height;
+    const sentinelTop = elementHeight + offset;
     if (debug) {
         // Debug mode: visible primary color line (cyan #00e0ff)
         sentinel.style.cssText =
-            `position:absolute;top:${elementHeight}px;left:0;right:0;height:3px;background:#00e0ff;margin:0;padding:0;box-sizing:border-box;z-index:999;pointer-events:none`;
+            `position:absolute;top:${sentinelTop}px;left:0;right:0;height:3px;background:#00e0ff;margin:0;padding:0;box-sizing:border-box;z-index:999;pointer-events:none`;
         sentinel.setAttribute('data-sentinel-debug', 'true');
     }
     else {
         // Production: invisible positioned absolutely (no layout impact)
         sentinel.style.cssText =
-            `position:absolute;top:${elementHeight}px;left:0;right:0;height:1px;visibility:hidden;margin:0;padding:0;box-sizing:border-box;pointer-events:none`;
+            `position:absolute;top:${sentinelTop}px;left:0;right:0;height:1px;visibility:hidden;margin:0;padding:0;box-sizing:border-box;pointer-events:none`;
     }
     return sentinel;
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { RuneScrollerOptions, AnimateOptions, IntersectionOptions, UseIntersectionReturn } from './types';
 export type { AnimationType } from './animations';
-export { runeScroller as default } from './runeScroller.svelte.js';
-export { animate } from './animate.svelte.js';
-export { useIntersection, useIntersectionOnce } from './useIntersection.svelte.js';
+export { runeScroller as default } from './runeScroller.svelte';
+export { animate } from './animate.svelte';
+export { useIntersection, useIntersectionOnce } from './useIntersection.svelte';
 export { calculateRootMargin } from './animations';

package/dist/runeScroller.svelte.js

@@ -24,19 +24,17 @@ export function runeScroller(element, options) {
         setupAnimationElement(element, options.animation);
         setCSSVariables(element, options.duration);
     }
+    // Créer un wrapper div autour de l'élément pour le sentinel en position absolute
+    // Ceci évite de casser le flex/grid flow du parent
+    const wrapper = document.createElement('div');
+    wrapper.style.cssText = 'position:relative;display:contents';
+    // Insérer le wrapper avant l'élément
+    element.insertAdjacentElement('beforebegin', wrapper);
+    wrapper.appendChild(element);
     // Créer le sentinel invisible (ou visible si debug=true)
-    // Sentinel positioned absolutely relative to parent (stays fixed while element animates)
-    const sentinel = createSentinel(element, options?.debug);
-    const parent = element.parentElement;
-    if (parent) {
-        // Ensure parent has position context for absolute positioning
-        const parentPosition = window.getComputedStyle(parent).position;
-        if (parentPosition === 'static') {
-            parent.style.position = 'relative';
-        }
-        // Insert sentinel after element, positioned absolutely
-        element.insertAdjacentElement('afterend', sentinel);
-    }
+    // Sentinel positioned absolutely relative to wrapper
+    const sentinel = createSentinel(element, options?.debug, options?.offset);
+    wrapper.appendChild(sentinel);
     // Observer le sentinel avec cleanup tracking
     let observerConnected = true;
     const observer = new IntersectionObserver((entries) => {
@@ -74,6 +72,12 @@ export function runeScroller(element, options) {
                 observer.disconnect();
             }
             sentinel.remove();
+            // Unwrap element (move it out of wrapper)
+            const parent = wrapper.parentElement;
+            if (parent) {
+                wrapper.insertAdjacentElement('beforebegin', element);
+            }
+            wrapper.remove();
         }
     };
 }

package/dist/types.d.ts

@@ -12,6 +12,7 @@ export interface RuneScrollerOptions {
     duration?: number;
     repeat?: boolean;
     debug?: boolean;
+    offset?: number;
 }
 /**
  * Options for the animate action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rune-scroller",
-  "version": "0.1.10",
+  "version": "1.0.0",
   "description": "Lightweight, high-performance scroll animations for Svelte 5. ~2KB bundle, zero dependencies.",
   "type": "module",
   "sideEffects": false,
@@ -40,6 +40,19 @@
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "svelte-package && node scripts/fix-dist.js",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "prettier --write .",
+    "lint": "prettier --check . && eslint .",
+    "prepublishonly": "pnpm run check && pnpm run build",
+    "test:unit": "vitest",
+    "test": "npm run test:unit -- --run"
+  },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
     "@eslint/js": "^9.36.0",
@@ -59,17 +72,5 @@
     "typescript-eslint": "^8.44.1",
     "vite": "^7.1.7",
     "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "dev": "vite dev",
-    "build": "svelte-package && node scripts/fix-dist.js",
-    "preview": "vite preview",
-    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
-    "format": "prettier --write .",
-    "lint": "prettier --check . && eslint .",
-    "prepublishonly": "pnpm run check && pnpm run build",
-    "test:unit": "vitest",
-    "test": "npm run test:unit -- --run"
   }
-}
+}