@rokkit/actions 1.0.0-next.128 → 1.0.0-next.129

package/dist/reveal.svelte.d.ts

@@ -1,6 +1,7 @@
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  *
  * @param {HTMLElement} node
  * @param {RevealOptions} [options]
@@ -10,6 +11,7 @@
  * @property {string} [distance='1.5rem'] Slide distance (CSS unit)
  * @property {number} [duration=600] Animation duration (ms)
  * @property {number} [delay=0] Delay before animation starts (ms)
+ * @property {number} [stagger=0] Delay increment per child in ms (0 = disabled)
  * @property {boolean} [once=true] Only animate once
  * @property {number} [threshold=0.1] IntersectionObserver threshold (0–1)
  * @property {string} [easing='cubic-bezier(0.4, 0, 0.2, 1)'] CSS easing function
@@ -18,6 +20,7 @@ export function reveal(node: HTMLElement, options?: RevealOptions): void;
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  */
 export type RevealOptions = {
     /**
@@ -36,6 +39,10 @@ export type RevealOptions = {
      * Delay before animation starts (ms)
      */
     delay?: number | undefined;
+    /**
+     * Delay increment per child in ms (0 = disabled)
+     */
+    stagger?: number | undefined;
     /**
      * Only animate once
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/actions",
-  "version": "1.0.0-next.128",
+  "version": "1.0.0-next.129",
   "description": "Contains generic actions that can be used in various components.",
   "author": "Jerry Thomas <me@jerrythomas.name>",
   "license": "MIT",

package/src/reveal.svelte.js

@@ -1,6 +1,7 @@
 /**
  * Scroll-triggered reveal action using IntersectionObserver.
  * Applies CSS transitions (opacity + translate) when element enters viewport.
+ * When stagger > 0, applies reveal to each child element independently.
  *
  * @param {HTMLElement} node
  * @param {RevealOptions} [options]
@@ -10,6 +11,7 @@
  * @property {string} [distance='1.5rem'] Slide distance (CSS unit)
  * @property {number} [duration=600] Animation duration (ms)
  * @property {number} [delay=0] Delay before animation starts (ms)
+ * @property {number} [stagger=0] Delay increment per child in ms (0 = disabled)
  * @property {boolean} [once=true] Only animate once
  * @property {number} [threshold=0.1] IntersectionObserver threshold (0–1)
  * @property {string} [easing='cubic-bezier(0.4, 0, 0.2, 1)'] CSS easing function
@@ -21,6 +23,7 @@ export function reveal(node, options = {}) {
 			distance: '1.5rem',
 			duration: 600,
 			delay: 0,
+			stagger: 0,
 			once: true,
 			threshold: 0.1,
 			easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
@@ -31,39 +34,80 @@ export function reveal(node, options = {}) {
 			typeof window !== 'undefined' &&
 			window.matchMedia('(prefers-reduced-motion: reduce)').matches
 
-		// Set CSS custom properties for the transition
-		node.style.setProperty('--reveal-duration', `${opts.duration}ms`)
-		node.style.setProperty('--reveal-distance', opts.distance)
-		node.style.setProperty('--reveal-easing', opts.easing)
+		const isStagger = opts.stagger > 0
 
-		// Apply direction attribute (CSS uses this for initial translate)
-		node.setAttribute('data-reveal', opts.direction)
+		function applyReveal(el) {
+			el.style.setProperty('--reveal-duration', `${opts.duration}ms`)
+			el.style.setProperty('--reveal-distance', opts.distance)
+			el.style.setProperty('--reveal-easing', opts.easing)
+			el.setAttribute('data-reveal', opts.direction)
+		}
+
+		function cleanReveal(el) {
+			el.removeAttribute('data-reveal')
+			el.removeAttribute('data-reveal-visible')
+			el.style.removeProperty('--reveal-duration')
+			el.style.removeProperty('--reveal-distance')
+			el.style.removeProperty('--reveal-easing')
+			el.style.removeProperty('transition-delay')
+		}
 
-		if (opts.delay > 0) {
-			node.style.transitionDelay = `${opts.delay}ms`
+		if (isStagger) {
+			Array.from(node.children).forEach((child) => applyReveal(child))
+		} else {
+			applyReveal(node)
+			if (opts.delay > 0) {
+				node.style.transitionDelay = `${opts.delay}ms`
+			}
 		}
 
 		if (reducedMotion) {
-			node.setAttribute('data-reveal-visible', '')
+			if (isStagger) {
+				Array.from(node.children).forEach((child) => child.setAttribute('data-reveal-visible', ''))
+			} else {
+				node.setAttribute('data-reveal-visible', '')
+			}
 			node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
 			return () => {
-				node.removeAttribute('data-reveal')
-				node.removeAttribute('data-reveal-visible')
-				node.style.removeProperty('--reveal-duration')
-				node.style.removeProperty('--reveal-distance')
-				node.style.removeProperty('--reveal-easing')
+				if (isStagger) {
+					Array.from(node.children).forEach((child) => cleanReveal(child))
+				} else {
+					cleanReveal(node)
+				}
 			}
 		}
 
+		let timers = []
+
 		const observer = new IntersectionObserver(
 			(entries) => {
 				for (const entry of entries) {
 					if (entry.isIntersecting) {
-						node.setAttribute('data-reveal-visible', '')
+						if (isStagger) {
+							timers.forEach((t) => clearTimeout(t))
+							const kids = Array.from(node.children)
+							timers = kids.map((child, i) => {
+								if (!child.hasAttribute('data-reveal')) applyReveal(child)
+								return setTimeout(
+									() => child.setAttribute('data-reveal-visible', ''),
+									opts.delay + i * opts.stagger
+								)
+							})
+						} else {
+							node.setAttribute('data-reveal-visible', '')
+						}
 						node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: true } }))
 						if (opts.once) observer.unobserve(node)
 					} else if (!opts.once) {
-						node.removeAttribute('data-reveal-visible')
+						if (isStagger) {
+							timers.forEach((t) => clearTimeout(t))
+							timers = []
+							Array.from(node.children).forEach((child) =>
+								child.removeAttribute('data-reveal-visible')
+							)
+						} else {
+							node.removeAttribute('data-reveal-visible')
+						}
 						node.dispatchEvent(new CustomEvent('reveal', { detail: { visible: false } }))
 					}
 				}
@@ -74,13 +118,13 @@ export function reveal(node, options = {}) {
 		observer.observe(node)
 
 		return () => {
+			timers.forEach((t) => clearTimeout(t))
 			observer.disconnect()
-			node.removeAttribute('data-reveal')
-			node.removeAttribute('data-reveal-visible')
-			node.style.removeProperty('--reveal-duration')
-			node.style.removeProperty('--reveal-distance')
-			node.style.removeProperty('--reveal-easing')
-			if (opts.delay > 0) node.style.removeProperty('transition-delay')
+			if (isStagger) {
+				Array.from(node.children).forEach((child) => cleanReveal(child))
+			} else {
+				cleanReveal(node)
+			}
 		}
 	})
 }