Implement viewEnter types alternate/repeat/state (#51)

* Implement viewEnter types alternate/repeat/state

* Fix cleanup of exit observer only if necessary

Author: ydaniv

packages/interact/dev/VIEW_ENTER_SPEC.md

@@ -0,0 +1,28 @@
+# `viewEnter` Beyond `type: 'once'`
+
+This is specification document for implementing the rest of the values for `type` property of `params` for `trigger: 'viewEnter'`.
+
+* Currently only `type: once` is implemented for the `viewEnter` trigger  
+* Other types that should also be implemented are: `alternate`, `repeat`, and `state`  
+* The initial flow for Interactions with these types are the same as for `once`  
+* These types should also track when the element exits the range \- `isIntersecting: false`  
+* We’ll start by using a default exit observer for each type \- without providing an API to specify its options  
+* We need to make sure we [persist](https://developer.mozilla.org/en-US/docs/Web/API/Animation/persist) the animation on these types.
+
+# `alternate`
+
+* When exiting the range the animation should be reversed.  
+* On subsequent re-entry the animation should be reversed (not play, since it was reversed on last exit)  
+* By default we can use the same observer as the one for entry.
+
+# `repeat`
+
+* By default we can use a separate observer that watches when the element is completely out of view  
+* When exiting the range the animation should be paused and set its progress to 0 (like “stop”).  
+* On subsequent re-entry the animation should be played from 0
+
+# `state`
+
+* By default we can use a separate observer that watches when the element is completely out of view  
+* When exiting the range the animation should be paused.  
+* On subsequent re-entry the animation should be resumed (calling `.play()` should resume it)

packages/interact/src/handlers/viewEnter.ts

@@ -14,16 +14,52 @@ const SAFE_OBSERVER_CONFIG: IntersectionObserverInit = {
   threshold: [0],
 };
 
+// Exit observer config for repeat/state types - watches when element is completely out of view
+const EXIT_OBSERVER_CONFIG: IntersectionObserverInit = {
+  root: null,
+  rootMargin: '0px',
+  threshold: [0],
+};
+
 const observers: Record<string, IntersectionObserver> = {};
 const handlerMap = new WeakMap() as HandlerObjectMap;
 const elementFirstRun = new WeakSet<HTMLElement>();
 const elementObserverMap = new WeakMap<HTMLElement, IntersectionObserver>();
 let viewEnterOptions: Partial<ViewEnterParams> = {};
+let sharedExitObserver: IntersectionObserver | null = null;
 
 function setOptions(options: Partial<ViewEnterParams>) {
   viewEnterOptions = options;
 }
 
+function invokeHandlers(target: HTMLElement, isIntersecting: boolean) {
+  const handlers = handlerMap.get(target);
+  handlers?.forEach(({ source, handler }) => {
+    if (source === target) {
+      handler!(isIntersecting);
+    }
+  });
+}
+
+function getExitObserver() {
+  if (sharedExitObserver) {
+    return sharedExitObserver;
+  }
+
+  sharedExitObserver = new IntersectionObserver((entries) => {
+    entries.forEach((entry) => {
+      const target = entry.target as HTMLElement;
+
+      if (!entry.isIntersecting) {
+        // Element has completely exited the view
+        invokeHandlers(target, false);
+      }
+    });
+  }, EXIT_OBSERVER_CONFIG);
+
+  return sharedExitObserver;
+}
+
 function getObserver(options: ViewEnterParams, isSafeMode: boolean = false) {
   const key = JSON.stringify({ ...options, isSafeMode });
 
@@ -78,20 +114,19 @@ const observer = new IntersectionObserver((entries) => {
       }
     }
 
-    if (entry.isIntersecting) {
-      const handlers = handlerMap.get(target);
+    const type = options.type || 'once';
 
-      handlers?.forEach(({ source, handler }) => {
-        if (source === entry.target) {
-          handler!();
-        }
-      });
+    if (entry.isIntersecting || (type === 'alternate' && !isFirstRun)) {
+      // For alternate type, handle exit using same observer as entry
+      invokeHandlers(target, entry.isIntersecting);
 
-      if (options.type === 'once') {
+      if (type === 'once') {
         observer.unobserve(entry.target);
         elementFirstRun.delete(target);
       }
     }
+    // Note: repeat and state exit handling is done by a separate exit observer
+    // that watches when element is completely out of view
   });
 }, config);
 
@@ -107,31 +142,81 @@ function addViewEnterHandler(
   options: ViewEnterParams = {},
   { reducedMotion, selectorCondition }: InteractOptions = {},
 ) {
-  const observer = getObserver({ ...viewEnterOptions, ...options });
+  const mergedOptions = { ...viewEnterOptions, ...options };
+  const observer = getObserver(mergedOptions);
+  const type = mergedOptions.type || 'once';
   const animation = getAnimation(
     target,
     effectToAnimationOptions(effect),
     undefined,
     reducedMotion,
   ) as AnimationGroup;
 
-  if (animation?.isCSS && options.type === 'once') {
+  // Persist animation for non-once types to prevent auto-cleanup
+  if (type !== 'once') {
+    // Use persist() if available (Web Animations API)
+    (animation as AnimationGroup & { persist?: () => void }).persist?.();
+  }
+
+  // Track initial play state for alternate type
+  let isInitialPlay = true;
+
+  if (animation?.isCSS) {
     animation.onFinish(() => {
       target.dataset.motionEnter = 'done';
     });
   }
 
-  const handler = () => {
+  const handler = (isIntersecting?: boolean) => {
     if (selectorCondition && !target.matches(selectorCondition)) return;
-    animation.play(() => {
-      if (!animation.isCSS) {
-        target.dataset.motionEnter = 'done';
+
+    if (type === 'once') {
+      if (isIntersecting) {
+        animation.play(() => {
+          if (!animation.isCSS) {
+            target.dataset.motionEnter = 'done';
+          }
+        });
       }
-    });
+    } else if (type === 'alternate') {
+      if (isInitialPlay && isIntersecting) {
+        isInitialPlay = false;
+        animation.play();
+      } else if (!isInitialPlay) {
+        // On subsequent entry/exit reverse the animation
+        animation.reverse();
+      }
+    } else if (type === 'repeat') {
+      if (isIntersecting) {
+        // On entry, reset progress to 0 before playing since the exit is a separate observer/range
+        animation.progress(0);
+        animation.play();
+      } else {
+        // On exit (completely out of view), pause and reset
+        animation.pause();
+        animation.progress(0);
+      }
+    } else if (type === 'state') {
+      if (isIntersecting) {
+        // Resume or start playing
+        animation.play();
+      } else {
+        // On exit (completely out of view), just pause
+        animation.pause();
+      }
+    }
   };
+
   const cleanup = () => {
     const currentObserver = elementObserverMap.get(source) || observer;
     currentObserver.unobserve(source);
+
+    if (type === 'repeat' || type === 'state') {
+      // Clean up exit observer if it exists
+      const exitObserver = getExitObserver();
+      exitObserver.unobserve(source);
+    }
+
     animation.cancel();
     elementFirstRun.delete(source);
     elementObserverMap.delete(source);
@@ -143,14 +228,27 @@ function addViewEnterHandler(
 
   elementObserverMap.set(source, observer);
   observer.observe(source);
+
+  // For repeat and state types, set up a separate exit observer
+  // that watches when element is completely out of view
+  if (type === 'repeat' || type === 'state') {
+    const exitObserver = getExitObserver();
+    exitObserver.observe(source);
+  }
 }
 
 function removeViewEnterHandler(element: HTMLElement) {
   removeElementFromHandlerMap(handlerMap, element);
 }
 
+function reset() {
+  sharedExitObserver = null;
+  Object.keys(observers).forEach((key) => delete observers[key]);
+}
+
 export default {
   add: addViewEnterHandler,
   remove: removeViewEnterHandler,
   setOptions,
+  reset,
 };

packages/interact/src/types.ts

@@ -32,7 +32,7 @@ export type TriggerType =
   | 'activate'
   | 'interest';
 
-export type ViewEnterType = 'once' | 'repeat' | 'alternate';
+export type ViewEnterType = 'once' | 'repeat' | 'alternate' | 'state';
 
 export type TransitionMethod = 'add' | 'remove' | 'toggle' | 'clear';
 
@@ -251,7 +251,7 @@ export type HandlerObject = {
   source: HTMLElement;
   target: HTMLElement;
   cleanup: () => void;
-  handler?: () => void;
+  handler?: (isIntersecting?: boolean) => void;
 };
 
 export type HandlerObjectMap = WeakMap<HTMLElement, Set<HandlerObject>>;