pagewave 1.0.0 → 1.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pagewave",
-  "version": "1.0.0",
-  "description": "NPM Package for implementing page transitions in both SSR and CSR apps",
+  "version": "1.0.1",
+  "description": "NPM Package for implementing page transitions in both SSR and CSR apps. Utilize both custom and preset animations. Choose between transitions, keyframe animations, and overlays.",
   "main": "transition.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -17,6 +17,6 @@
   "license": "ISC",
   "repository": {
     "type": "git",
-    "url": "https://github.com/toasterstrudelz/pagewave.git"
+    "url": "https://github.com/danielpagano202/pagewave.git"
   }
 }

package/transition.js

@@ -1,3 +1,4 @@
+//Default Options
 let defaultOptions = {
     mainContentIdName: "main-content",
     overlayClass: "a-overlay",
@@ -13,7 +14,10 @@ let defaultOptions = {
     animateIgnoredLinks: false,
     animateSelfLink: true,
     loadEvent: "DOMContentLoaded",
+    usePresets: true,
+    cleanUpDivs: false,
 }
+//Options object that will contain the actual options used by the program
 let finalOptions = {
     mainContentIdName: "main-content",
     overlayClass: "a-overlay",
@@ -29,22 +33,28 @@ let finalOptions = {
     animateIgnoredLinks: false,
     animateSelfLink: true,
     loadEvent: "DOMContentLoaded",
+    usePresets: true,
+    cleanUpDivs: false,
 }
 
+//Sets Up Page Transition Capability. Not necessary if you don't need options or presets
 function SetUp(options = {}) {
     //Merge default options with user options
     finalOptions = { ...defaultOptions, ...options };
-    //Import css files into HTNL document
-    let cssFiles = ["OverlayPreset.css", "KeyFramePreset.css"];
-    for (let i = 0; i < cssFiles.length; i++) {
-        let link = document.createElement('link');
-        link.rel = 'stylesheet';
-        link.type = 'text/css';
-        link.href = cssFiles[i];
-        document.getElementsByTagName('HEAD')[0].appendChild(link);
+    //Import css files into HTML document automatically
+    if(finalOptions.usePresets){
+        let cssFiles = ["OverlayPreset.css", "KeyFramePreset.css"];
+        for (let i = 0; i < cssFiles.length; i++) {
+            let link = document.createElement('link');
+            link.rel = 'stylesheet';
+            link.type = 'text/css';
+            link.href = cssFiles[i];
+            document.getElementsByTagName('HEAD')[0].appendChild(link);
+        }
     }
 }
 exports.SetUp = SetUp;
+//Overlay Preset Types to Choose From
 const overlayType = Object.freeze({
     slide: Symbol("slide"),
     inverseSlide: Symbol("inverseSlide"),
@@ -54,12 +64,14 @@ const overlayType = Object.freeze({
     bubble: Symbol("bubble"),
 });
 exports.overlayType = overlayType;
+//Keyframe Preset Types to Choose From
 const keyframeType = Object.freeze({
     fade: Symbol("fade"),
     fadeaway: Symbol("fadeaway"),
 });
 exports.keyframeType = keyframeType;
 
+//Function to apply animation to element and keep its properties and remove the animation
 function ApplyAnimation(element, animationName, duration, timing, direction) {
     element.style.animation = `${animationName} ${duration}ms ${timing} both ${direction}`;
     if (direction == "reverse") {
@@ -86,6 +98,7 @@ function ApplyAnimation(element, animationName, duration, timing, direction) {
         element.addEventListener("animationend", handleAnimation,);
     }
 }
+//Dispatch an event for the hooks
 function CallHook(hookName, details) {
     const event = new CustomEvent(hookName, {
         detail: details
@@ -104,6 +117,7 @@ class KeyFramePreset {
             fade: "fade",
             fadeaway: "fadeaway"
         };
+        //Uses keyframeType to run Keyframe Custom
         if (animationMap[this.kfType.description]) {
             AnimatePageTransition(new KeyFrameCustom(animationMap[this.kfType.description], this.duration, this.timing), direction);
         }
@@ -117,6 +131,7 @@ class KeyFrameCustom {
         this.timing = timing;
     }
     handle(direction, mainElement) {
+        //Reveals element and applys the animation
         mainElement.hidden = false;
         ApplyAnimation(mainElement, this.animationName, this.duration, this.timing, direction)
     }
@@ -131,6 +146,7 @@ class StyleTransition {
         this.timing = timing;
     }
     handle(direction, mainElement) {
+        //Applys the transition in the right direction
         if (direction == "normal") {
             mainElement.style[this.styleString] = this.startValue;
             mainElement.style.transition = this.styleString + " " + this.duration.toString() + "ms " + this.timing;
@@ -138,6 +154,7 @@ class StyleTransition {
         } else if (direction == "reverse") {
             mainElement.style[this.styleString] = this.endValue;
             mainElement.style.transition = this.styleString + " " + this.duration.toString() + "ms " + this.timing;
+            //Timeout is needed for some reason. Need to test further but it works
             setTimeout(
                 () => {
                     mainElement.style[this.styleString] = this.startValue;
@@ -158,9 +175,11 @@ class MultiElementAnimation {
     handle(direction, mainElement) {
         mainElement.hidden = false;
         let timing = this.timing;
+        //Goes through every animation selector, finds all of those elements, and applies the proper animation to them
         for (const [selector, animationName] of Object.entries(this.animateableObjects)) {
             document.querySelectorAll(selector).forEach(element => ApplyAnimation(element, animationName, this.duration, timing, direction));
         }
+        //Animates main element if animation is given
         if (this.mainElementAnimation != "") {
             ApplyAnimation(mainElement, this.mainElementAnimation, this.duration, timing, direction);
         }
@@ -175,6 +194,7 @@ class OverlayPreset {
         this.timing = timing;
     }
     handle(direction) {
+        //Finds the proper preset and runs OverlayCustom appropriately
         const overlayMap = {
             slide: { firstOverlayElement: "slide" },
             inverseSlide: { firstOverlayElement: "inverseSlide" },
@@ -201,21 +221,26 @@ class OverlayCustom {
         var r = document.querySelector(':root');
         r.style.setProperty('--div-color', this.color);
         let timing = this.timing;
-        /*
+        //Removes divs when animation is finished
         function RemoveDiv(event) {
             if (event.target.animateName == event.animationName) {
                 event.target.removeEventListener("animationend", RemoveDiv);
                 event.target.remove();
             }
-        }*/
+        }
+        //Loops through divs, creating them, adding the provided class, and giving them an animation
         for (const [className, animationName] of Object.entries(this.divAnimationObject)) {
             let divElement = document.createElement("div");
             divElement.className = className;
             divElement.style.animation = `${animationName} ${this.duration.toString()}ms ${timing} both ${direction}`;
             mainElement.appendChild(divElement);
-            //divElement.animateName = animationName;
-            //divElement.addEventListener("animationend", RemoveDiv);
+            //Removes divs at end of animation
+            if(finalOptions.cleanUpDivs){
+                divElement.animateName = animationName;
+                divElement.addEventListener("animationend", RemoveDiv);
+            }
         }
+        //Animates main element if animation is given
         if (this.mainElementAnimation != "") {
             mainElement.style.animation = `${this.mainElementAnimation} ${this.duration.toString()}ms ${timing} both ${direction}`;
         }
@@ -232,7 +257,7 @@ function AddFileToCache(file) {
         }
     }
 }*/
-
+//Adds service worker to cache presets and this script. Returns a boolean true if it is already active or useServiceWorker was overrided; false otherwise
 function AddServiceWorker() {
     if (!finalOptions.useServiceWorker) {
         return true;
@@ -248,7 +273,7 @@ function AddServiceWorker() {
     }
     return isServiceWorker;
 }
-
+//Checks if navigation is from same site. Returns false if referrer and current host are different of refferer is empty
 function isNavigationFromSameSite() {
     const referrer = document.referrer;
     if (referrer == "") {
@@ -259,7 +284,7 @@ function isNavigationFromSameSite() {
 
     return referrerHost === currentHost;
 }
-
+//Returns true if animation is overlay type, false if animation type
 function IsOverlay(transitionStyle) {
     if (transitionStyle instanceof OverlayPreset || transitionStyle instanceof OverlayCustom) {
         return true;
@@ -268,6 +293,7 @@ function IsOverlay(transitionStyle) {
     }
 }
 exports.IsOverlay = IsOverlay;
+//Checks if element exists. If it does, it runs functionToExecute. Otherwise, waits until element exists to run the function
 function WaitForElementLoad(selector, functionToExecute) {
     if(document.querySelector(selector) != null){
         functionToExecute(document.querySelector(selector));
@@ -287,20 +313,25 @@ function WaitForElementLoad(selector, functionToExecute) {
     observer.observe(document.body, { childList: true, subtree: true });
 }
 exports.WaitForElementLoad = WaitForElementLoad;
+//Shorthand for SendPoint and EndPoint
 function ListenForChange(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction = (link) => {window.location = link;}) {
     EndPoint(aStyle, aOverlay, aAnimation, leaveFunction);
     SendPoint(aStyle, aOverlay, aAnimation);
 }
 exports.ListenForChange = ListenForChange;
+//Listens for clicks and plays animation and then redirects
 function SendPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction = (link) => {window.location = link;}) {
+    //True if service worker is active or ignored with useServiceWorker=false, false otherwise
     let allowAnimate = AddServiceWorker();
 
     function HandleClickAnimation(e) {
-        //console.log(e.target.tagName, e.target.classList, e.target.href == window.location.href, finalOptions.animateSelfLink)
-        if (e.target.tagName.toLowerCase() == "a" && !(e.target.classList.contains(finalOptions.classToIgnoreLink)) && !(e.target.href == window.location.href && !finalOptions.animateSelfLink)) {
+        //Checks to see if target is a link, it is not a link to ignore, not a self link + animateSelfLink=false
+        if (e.target.tagName == "A" && !(e.target.classList.contains(finalOptions.classToIgnoreLink)) && !(e.target.href == window.location.href && !finalOptions.animateSelfLink)) {
+            //Prevents link from redirecting
             e.preventDefault();
             let duration = aStyle.duration;
             CallHook("animateSSP", { style: aStyle, overlayStyle: aOverlay, animationStyle: aAnimation, clickEvent: e });
+            //Plays the right animation depending on link type and sets proper duration
             if (e.target.classList.contains(finalOptions.overlayClass)) {
                 AnimatePageTransition(aOverlay, "normal");
                 duration = aOverlay.duration;
@@ -311,6 +342,7 @@ function SendPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction
                 AnimatePageTransition(aStyle, "normal");
                 duration = aStyle.duration;
             }
+            //Calls the leave function when duration timer finishes
             setTimeout(
                 () => {
                     CallHook("animateESP", { style: aStyle, overlayStyle: aOverlay, animationStyle: aAnimation, clickEvent: e });
@@ -320,6 +352,7 @@ function SendPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction
                     }
                 }, parseInt(duration)
             );
+        //We set the storage to ignore so we don't play an animation when we go to another page.
         } else if (e.target.classList.contains(finalOptions.classToIgnoreLink) || (e.target.href == window.location.href && !finalOptions.animateSelfLink)) {
             sessionStorage.setItem("animationType", "ignore");
         }
@@ -329,9 +362,11 @@ function SendPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction
     function AddListeners() {
         window.addEventListener("click", HandleClickAnimation);
     }
+    //If service worker active, can immediately listen
     if (allowAnimate) {
         AddListeners();
     }
+    //Else, wait until the loadEvent provided is triggered
     else {
         window.addEventListener(finalOptions.loadEvent, () => {
             AddListeners();
@@ -339,7 +374,9 @@ function SendPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle, leaveFunction
     }
 }
 exports.SendPoint = SendPoint;
+//Waits for the document to load and plays the reverse animation
 function EndPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle) {
+    //Checks to see what kind of receiving animation to play
     if (aOverlay != aStyle || aAnimation != aStyle) {
         if (sessionStorage.getItem("animationType") === "true") {
             aStyle = aOverlay;
@@ -373,9 +410,9 @@ function EndPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle) {
             }
         }
     }
-
+    //True if service worker is active or ignored with useServiceWorker=false, false otherwise
     let allowAnimate = AddServiceWorker();
-    //console.log("allow animating");
+    //Figures out what kind of animation it is and hides the document properly
     if (IsOverlay(aStyle)) {
         RevealPage(true);
         let pageBlocker = document.createElement('div');
@@ -394,16 +431,19 @@ function EndPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle) {
             document.getElementById(finalOptions.mainContentIdName).hidden = true;
         }
     }
-    //console.log(allowAnimate, !(!finalOptions.animateIgnoredLinks && sessionStorage.getItem("animationType") == "ignore"), !(!finalOptions.animateSelfLink && sessionStorage.getItem("animationType") == "ignore"))
-    if (allowAnimate && !(!finalOptions.animateIgnoredLinks && sessionStorage.getItem("animationType") == "ignore") && !(!finalOptions.animateSelfLink && sessionStorage.getItem("animationType") == "ignore")) {
+    //Checks to see if allowAnimate=true and we aren't supposed to be ignoring the link
+    if (allowAnimate && !(sessionStorage.getItem("animationType") === "ignore" && (finalOptions.animateIgnoredLinks || finalOptions.animateSelfLink))){        
+        //Once the load evnet is triggered, it registers a listener
         window.addEventListener(finalOptions.loadEvent, (e) => {
             e.stopPropagation();
             CallHook("animateSEP", { style: aStyle });
-            //console.log(window.performance.getEntriesByType("navigation")[0].type, isNavigationFromSameSite(), finalOptions.runAnimationOnCrossSite)
+            //If we reloaded, we want to make sure runAnimationOnPageReload is false and if we came from a different site, we want to make sure we can run animation on cross site
             if ((window.performance.getEntriesByType("navigation")[0].type != "reload" || finalOptions.runAnimationOnPageReload) && (isNavigationFromSameSite() || finalOptions.runAnimationOnCrossSite)) {
+                //Uses a delay between this to keep the document hidden for extra if the load event isn't trusted
                 setTimeout(
                     () => {
                         AnimatePageTransition(aStyle, "reverse");
+                        //Delay between animation and reveal
                         setTimeout(
                             () => {
                                 CallHook("animateEEP", { style: aStyle });
@@ -413,11 +453,13 @@ function EndPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle) {
                     }, finalOptions.pageAnimationDelay
                 );
             } else {
+                //Reveals page after document is built
                 CallHook("animateEPNA", { style: aStyle })
                 RevealPage();
             }
         }, { once: true });
     } else {
+        //Waits for load and Reveals the Page
         window.addEventListener(finalOptions.loadEvent, () => {
             CallHook("animateEPNSW", { style: aStyle })
             RevealPage();
@@ -425,9 +467,12 @@ function EndPoint(aStyle, aOverlay = aStyle, aAnimation = aStyle) {
     }
 }
 exports.EndPoint = EndPoint;
+//Animates the page transition
 function AnimatePageTransition(aStyle, direction = "normal") {
     let mainElement = document.getElementById(finalOptions.mainContentIdName);
+    //If we don't have a preset, we can call a hook because presets also call their custom variant
     if (!(aStyle instanceof OverlayPreset) && !(aStyle instanceof KeyFramePreset)) {
+        //Sets animationType in storage to allow EndPoint to change page transition element depending on type
         sessionStorage.setItem("animationType", IsOverlay(aStyle).toString());
         if (direction == "normal") {
             CallHook("animateSF", { style: aStyle, ele: mainElement, });
@@ -435,7 +480,9 @@ function AnimatePageTransition(aStyle, direction = "normal") {
             CallHook("animateSR", { style: aStyle, ele: mainElement, });
         }
     }
+    //Calls handle function of style element
     aStyle.handle(direction, mainElement);
+    //Same logic as above except for end hooks
     if (!(aStyle instanceof OverlayPreset) && !(aStyle instanceof KeyFramePreset)) {
         setTimeout(
             () => {

package/guide.txt

@@ -1,56 +0,0 @@
-Types of Animation Containers:
--KeyFramePreset
--KeyFrameCustom
--StyleTransition
--OverlayPreset
--OverlayCustom
--MultiElementAnimation
-
-Preset Types:
--Overlay Presets
--Keyframe Presets
-
-Animation Function:
--AnimatePageTransition
-
-Listener Functions:
--ListenForChange
--SendPoint
--EndPoint
-
-Hooks:
--animateSF - animation start forward
--animateSR - animation start reverse
--animateEF - animation end forward
--animateER - animation end reverse
--animateSSP - start of send point listen
--animateESP - end of send point listen
--animateSEP - start of end point listen
--animateEPNSW - end point no service worker exists
--animateEEP - end of end point
--animateEPNA - end point no animation played
-
-Features:
--Built-in animations
--Hooks
--Doesn't touch history or use push state, allowing
-for you to use it with routers like sveltekit
--Manual page transition animations can be run to avoid
-conflicts with any frameworks
--Customizable ids for divs to avoid conflict with elements
-in your body
--Allows for custom overlay animations, keyframe animations, or
-transition animations
--Separate listener animations for different types of animations
--Separate types of links for overlay or other animations
-
-What I Learned:
--Expanded knowledge on HTML, JS, and CSS Knowledge
--Session storage
--Service workers
--Polymorphism
--Event dispatcher
-
-Common Issues:
--White Flash
--Issues with using absolute positioning on main content and calling overlay animations