@linear_non/stellar-libs 1.0.29 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linear_non/stellar-libs",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "Reusable JavaScript libraries for Non-Linear Studio projects.",
   "main": "src/index.js",
   "type": "module",

package/src/SplitOnScroll/index.js

@@ -1,20 +1,20 @@
-import { splitText, reverseSplit, Observer } from "@linear_non/stellar-kit/plugins"
-import { EVENTS } from "@linear_non/stellar-kit/events"
-import { ScrollTrigger } from "@linear_non/stellar-kit/gsap"
+import { Observer, splitText } from "@linear_non/stellar-kit/plugins"
+import { EVENTS } from "../events"
 
 export default class SplitonScroll {
   constructor({
-    el,
+    trigger: el,
     splitText,
     isReady,
     reverse,
-    start = "top bottom", // "top top+=100%",
-    end = "bottom top", // "bottom bottom-=100%",
+    start = "top bottom",
+    end = "bottom top",
     scrub = false,
     once = true,
   }) {
     this.element = el
 
+    // Normalize split targets to an array
     if (!splitText) {
       this.targets = []
     } else if (splitText instanceof Element) {
@@ -25,17 +25,63 @@ export default class SplitonScroll {
       this.targets = Array.from(splitText)
     }
 
-    if (!this.targets.length) return
-
+    // SplitText() instance
     this.splits = null
-    this.isReadyCallback = isReady || (() => {})
+
+    // Grouped SplitText() instances from data-split-group
+    this.groups = null
+
+    // Backward-compatible isReady wrapper
+    //  isReady(splits) OR  isReady(splits, groups)  OR  isReady({ splits, groups })
+    this._userReady = typeof isReady === "function" ? isReady : null
+    this.isReadyCallback = (splits, groups) => {
+      if (!this._userReady) return
+
+      if (this._userReady.length === 0) {
+        // If callback expects 0 args, give it the object
+        this._userReady({ splits, groups })
+      } else if (this._userReady.length === 1) {
+        // If callback expects 1 arg, assume old-style: isReady(splits)
+        this._userReady(splits)
+      } else {
+        // 2+ args: new-style: isReady(splits, groups)
+        this._userReady(splits, groups)
+      }
+    }
+
     this.reverseCallback = reverse || (() => {})
     this.start = start
     this.end = end
     this.scrub = scrub
     this.once = once
 
+    // Expose a Promise so users can wait for ready event
+    this._resolveReady = null
+    this.ready = new Promise(resolve => {
+      this._resolveReady = resolve
+    })
+
+    // If no element or no targets, resolve immediately
+    if (!this.element || !this.targets.length) {
+      const splits = []
+      const groups = {}
+      const payload = { splits, groups }
+
+      if (this._resolveReady) {
+        this._resolveReady(payload)
+        this._resolveReady = null
+      }
+
+      this.isReadyCallback(splits, groups)
+      return
+    }
+
     this.addObserver()
+
+    // If already in view, trigger enter handler
+    if (this.observer.isActive || this.observer.progress > 0) {
+      this.handleEnter()
+    }
   }
 
   addObserver() {
@@ -53,18 +99,32 @@ export default class SplitonScroll {
 
   async handleEnter() {
     if (this.splits) {
-      this.isReadyCallback(this.splits)
+      this.isReadyCallback(this.splits, this.groups || {})
       return
     }
 
-    const split = splitText(this.targets)
-    const splits = await new Promise(resolve => {
-      split.on(EVENTS.APP_SPLITTEXT_READY, readySplits => {
-        resolve(readySplits)
+    const emitter = splitText(this.targets)
+
+    const { splits, groups } = await new Promise(resolve => {
+      emitter.on(EVENTS.APP_SPLITTEXT_READY, (readySplits, groupMap) => {
+        resolve({
+          splits: readySplits || [],
+          groups: groupMap || {},
+        })
       })
     })
+
     this.splits = splits
-    this.isReadyCallback(splits)
+    this.groups = groups
+
+    const payload = { splits, groups }
+
+    if (this._resolveReady) {
+      this._resolveReady(payload)
+      this._resolveReady = null
+    }
+
+    this.isReadyCallback(splits, groups)
   }
 
   handleLeave() {
@@ -86,6 +146,7 @@ export default class SplitonScroll {
   destroy() {
     this.observer?.kill()
     this.splits = null
+    this.groups = null
     this.targets = null
     this.element = null
   }