pagewave 1.0.4 → 1.0.6

package/README.md

@@ -1,331 +1,350 @@
-
-# PageWave
-
-An NPM Package for implementing page transitions in both SSR and CSR apps
-
-
-
-
-## Installation
-
-Downloading the project files from Github (Recommended to allow for service worker to cache pages effectively)
-
-Install my-project with npm
-
-```bash
-npm install pagewave
-```
-
-If gotten from NPM, service worker doesn't get added, so the optional parameter useServiceWorker needs to be false and pages should be cached for optimal transitions.
-    
-## 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
-
-
-## High Level Explanation
-
-This package involves two types of animations: Overlay and Keyframe.
-- Overlay involve colored divs that move on the screen i.e. screen wipe
-- Keyframe involve animations of existing animations i.e. fading away
-
-These two animations can be created through certain classes
-```javascript
-Style Transition 
-//Utilizes CSS transition to affect a certain value
-StyleTransition("opacity", 500, "1", "0")
-
-KeyFramePreset
-//Utilizes one of the packages presets to animate
-KeyFramePreset(keyframeType.fade, 250, "ease-in-out");
-
-KeyFrameCustom
-//Utilizes a custom animation
-KeyFrameCustom("move", 250, "ease-in-out");
-
-OverlayPreset
-//Utilizes one of the packages presets to animate Div overlay
-OverlayPreset(overlayType.bubble, 500, "#293241");
-
-OverlayCustom
-//Creates a custom animation of div(s)
-OverlayCustom(
-    {
-        "first": "rise",
-        "second": "fall",
-        "third": "slide",
-        "fourth": "inverseSlide",
-    }, 3000, "#293241", "ease-in-out"
-);
-
-MultiElementAnimation
-//Animates many elements independently in the transition
-MultiElementAnimation(
-    {
-        "h1": "move",
-        "p": "move",
-        ".other-header": "inverseMove",
-    }, 1000, "linear", "fadeAll"
-)
-```
-
-These styles of transition can be used in link clicks, page loads, and manually very easily through functions calls.
-
-## TGetting started
-
-```javascript
-    //Optional parameter can be ignored if not downloaded from npm
-    SetUp({useServiceWorker: false});
-```
-
-### Setting up an animation
-
-Tag the element that encapsulates the content with an id of 'main-content'
-
-If you can't do that, change the parameter name.
-
-```javascript
-    //Optional parameter can be ignored if not downloaded from npm
-    SetUp({useServiceWorker: false});
-
-    //Creates a style with preset bubble transition
-    //Length of 500ms and color of "#293241"
-    let aSty = new OverlayPreset(
-        overlayType.bubble, 500, "#293241"
-    );
-
-    //Makes links use transition and plays transition on page enter
-    ListenForChange(aSty);
-
-    //Alternatively, split it up if you want different animations for each
-
-    //Makes links use the transitions when going to page
-    SendPoint(aSty);
-
-    //Makes transition appear when arriving to this page
-    EndPoint(aSty);
-
-    
-
-```
-
-## Working with SSR
-
-Many of these features work flawlessly with CSR. 
-
-However, small changes need to be made depending on what SSR you are using.
-
-I tested this with Svelte as that is what I am familiar with.
-
-#### Changes
-
-- runAnimationOnPageReload needs to be set to true, because hydrating the page only counts as a reload, not a page change
-- loadEvent needs to be run independently. I would change it to "load" and call the event separately using dispatch event
-- SetUp may not automatically import the preset CSS files, so it may need to be done manually
-
-## Other Cool Features
-
-### Custom Keyframe Transitions
-
-This will create an animation style, that when called:
-
-Moves h1 and p elements to the left
-
-Moves h2 and elements with 'moving' class to the right
-
-This is over 1000ms, at a 'linear' pace, and fades everything
-
-Essentially you can specify specific transitions for certain classes and a global transition for everything
-
-
-```javascript
-SetUp();
-
-let anim = new MultiElementAnimation(
-    {
-        "h1": "move",
-        "p": "move",
-        "h2": "inverseMove",
-        ".moving": "inverseMove",
-    }, 1000, "linear", "fadeAll"
-);
-
-ListenForChange(anim);
-
-...
-
-<style>
-
-@keyframes move {
-    from{
-        transform: translate(0px, 0px);
-        color: black;
-        opacity: 1;
-    }
-    to{
-        transform: translate(-200px, 0px);
-        opacity: 0;
-        color: white;
-    }
-    
-}
-@keyframes inverseMove {
-    from{
-        transform: translate(0, 0px);
-        opacity: 1;
-    }
-    to{
-        transform: translate(200px, 0px);
-        opacity: 0;
-    }
-    
-}
-@keyframes fadeAll {
-    from{
-        opacity: 1;
-    }
-    to{
-        opacity: 0;
-    }
-}
-</style>
-
-```
-
-### Custom Overlay Transitions
-
-The same thing can be done with overlays
-
-This will run these transitions and the overlays will have the class names of 'first', 'second', etc.
-
-Run for 3000ms, with a color of #293241 and pace of 'ease-in-out'
-
-```javascript
-let aStyle = new OverlayCustom(
-    {
-        "first": "rise",
-        "second": "fall",
-        "third": "slide",
-        "fourth": "inverseSlide",
-    }, 3000, "#293241", "ease-in-out"
-);
-
-//Names are presets transitions, so check OverlayPreset.css to see the CSS
-
-```
-
-#### Manual Transitions
-
-You can do transitions manually through the ```AnimatePageTransition(style)``` function which takes an animation style as a parameter
-
-### Different Transitions
-
-You can have three different animations you can call in the ```SendPoint(), EndPoint(), or ListenForChange()``` function.
-
-For example:
-```
-let defaultAnimation = ...
-let overlayAnimation = ...
-let keyframeAnimation = ...
-SendPoint(defaultAnimation, overlayAnimation, keyframeAnimation);
-```
-
-You can specify which animation is called by adding classes to link.
-- a-overlay for overlayAnimation
-- a-animation for keyframeAnimation
-
-
-### Custom Link function
-
-By default, this package uses a default function of ```window.location = link;``` for changing links. However, this can be customized in either ```SendPoint() or ListenForChange()```
-
-```
-let defaultAnimation = ...
-let overlayAnimation = ...
-let keyframeAnimation = ...
-let linkFunction = (link) => {
-    console.log(link);
-    window.location = link;
-}
-SendPoint(defaultAnimation, overlayAnimation, keyframeAnimation, linkFunction);
-```
-
-This is useful in SSR when the link change function is different from the default one.
-
-### Events
-
-There are many events that can be listened to to call certain code.
-
-- animateSF - animation start, forward direction
-- animateSR - animation start, reverse direction
-- animateEF - animation end, forward direction
-- animateER - animation end, reverse direction
-- animateSSP - start of Send Point listening (when a link is clicked)
-- animateESP - end of Send Point listen (when the animation is handled)
-- animateSEP - start of end point listen (when the load event is dispatched)
-- animateEPNSW - end point no service worker exists (when there is no service worker and service workers are being used)
-- animateEEP - end of end point (when the page is revealed after an animation)
-- animateEPNA - end point no animation played (when the page is revealed but no animation was played)
-
-
-
-### This program has optional parameters:
-
-#### Optional Parameter Name : Default Value
-
-```javascript
-//This is the class for the content that the transition will affect/cover
-mainContentIdName: "main-content"
-
-//This is the class name that a button needs to cause the overlay transitions
-overlayClass: "a-overlay",
-
-//This is the class name that a button needs to cause the key frame transition
-animationClass: "a-animation",
-
-//This is the delay between the page loading and the page beginning the animation
-pageAnimationDelay: 200,
-
-//This is the whether to use a service worker. If using npm, service worker doesn't work, so this needs to be disabled!
-useServiceWorker: true,
-
-//Whether the transition should run when the page is reloaded
-//Sometimes needs to be enabled in SSR because of how they treat going from one page to another as reloading
-runAnimationOnPageReload: false,
-
-//Whether the transition should run when a link goes to a different page
-runAnimationOnCrossSite: false,
-
-//The delay between the animation playing and the page revealing
-pageRevealDelay: 0,
-
-//Whether the page should be left after animation
-leavePageOnLink: true,
-
-//What the ID of the element that blocks the page is
-pageBlockerId: "pageBlocker",
-
-//What class should be added to links to not transition
-classToIgnoreLink: "ignore-click",
-
-//Whether ignored links should animate
-animateIgnoredLinks: false,
-
-//Whether links to the same page should animate
-animateSelfLink: true,
-
-//The event that is checked to see that the page is loaded
-//Important to change on SSR because this event isn't automatically triggered
-loadEvent: "DOMContentLoaded",
-```
-
-## Supporting
-
-If you find this project helpful, considering starring it. I would greatly appreciate it! :)
+
+# PageWave
+
+An NPM Package for implementing page transitions in both SSR and CSR apps
+
+
+## Installation
+
+Install pagewave with npm
+
+```bash
+npm install pagewave
+```
+
+    
+## 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 animations based on class name of link
+- Preset transition classes to get up and running quickly
+- Highly customizable transition options
+- Extendable class system to create custom transition styles
+
+
+## High Level Explanation
+
+This package involves allows a user to set up certain routes with names and have those routes triggered either by clicking on a link, loading onto a page, or manually. 
+
+Utilize transtion classes premade or custom built to handle it.
+
+## Getting started
+
+At its core, 
+
+```typescript
+    import { PageWave, KeyFramePreset, StyleTransition, type KeyFrameType } from 'pagewave';
+    import "pagewave/KeyFramePreset.css";
+
+    let keyFrameType: KeyFrameType = "fadetoright";
+
+    let fadeToRightTransition = new KeyFrameCustom(
+        keyFrameType, 250, "ease-in-out"
+    );
+
+    let defaultTransition = new StyleTransition(
+        "opacity", 250, "1", "0"
+    );
+
+    const pw: PageWave = new PageWave(
+        {
+            "fade": fadeToRightTransition
+        },
+    );
+    
+    // The following code should be contained within a client function like Sveltekit onMount or React useLayoutEffect if being done in SSR
+
+    // Setups the transition to occur when loading onto page, with a default transition provided
+    pw.EndPoint(defaultTransition);
+
+    // Setups the transition to occur when a link is clicked, with a default transition provided
+	pw.SendPoint(defaultTransition);
+
+    // Called to start the endpoint
+	pw.CallEndPoint();
+```
+
+In this code, there are a few points to note:
+- The arguments in PageWave represent routes that are used by EndPoint and SendPoint
+- For SendPoint, if a link has the class "fade", it will run the fade animation when clicked, and then go to the link. It will also save in sessionStorage the name "fade" under animationType
+- This session storage is used in EndPoint as it looks for a route matching the saved value under animationType. In this code, it would look for fade and play that transition.
+- Just because two pages may have "fade" defined doesn't mean that they have to play the same animation
+- CallEndPoint is utilized in cases where the base event "DOMContentLoaded" isn't called on every page (like in SSR where the layout stays constant)
+
+### Setting up an animation
+
+Tag the element that encapsulates the content with an id of 'main-content'
+
+If you can't do that, change the parameter name.
+
+```html
+<script>
+    import { PageWave, KeyFramePreset, StyleTransition, type KeyFrameType } from 'pagewave'
+    import "pagewave/OverlayPreset.css";
+    let keyFrameType: OverlayType = "bubble";
+
+    let bubbleTransition = new OverlayPreset(
+        overlayType.bubble, 500, "#293241"
+    );
+
+    let defaultTransition = new StyleTransition(
+        "opacity", 250, "1", "0"
+    );
+
+    const pw: PageWave = new PageWave(
+        {
+            "pagewave-bubble": bubbleTransition
+        },
+        {
+            // These are options. This option is unnecessary as it defaults to "main-content", but showcasing you can change it
+            mainContentIdName: "main-content"
+        }
+    );
+    
+    // The following code should be contained within a client function like Sveltekit onMount or React useLayoutEffect if being done in SSR
+    
+    // Combines Endpoint and Sendpoint if you need individual control
+    pw.ListenForChange(defaultTransition);
+    pw.CallEndPoint();
+
+</script>
+
+<!--The area that you want to transition must be marked with id="main-content"-->
+<div id="main-content">
+    <h1>This is my page</h1>
+    <!-- This link transitions with the pagewave-bubble transition-->
+    <a href="..." class="pagewave-bubble">Click me to transition!</a>
+</div>
+
+```
+
+## Working with SSR
+
+Because of the nature of SSR, a few changes have to be made:
+- The Send and End Points function must be run in load functions as they make reference to the window for changing the link and dispatching events
+- You need to change the goto Function for SendPoint. Do this by `SendPoint(defaultTransition, () => {/* Function */})`
+
+## Other Cool Features
+
+### Custom Keyframe Transitions
+
+This will create an animation style, that when called:
+
+Moves h1 and p elements to the left
+
+Moves h2 and elements with 'moving' class to the right
+
+This is over 1000ms, at a 'linear' pace, and fades everything
+
+Essentially you can specify specific transitions for certain classes and a global transition for everything
+
+
+```javascript
+...
+
+let multiElementAnimation =l new MultiElementAnimation(
+    {
+        "h1": "move",
+        "p": "move",
+        "h2": "inverseMove",
+        ".moving": "inverseMove",
+    }, 1000, "linear", "fadeAll"
+);
+
+pw.ListenForChange(multiElementAnimation);
+
+...
+
+<style>
+
+@keyframes move {
+    from{
+        transform: translate(0px, 0px);
+        color: black;
+        opacity: 1;
+    }
+    to{
+        transform: translate(-200px, 0px);
+        opacity: 0;
+        color: white;
+    }
+    
+}
+@keyframes inverseMove {
+    from{
+        transform: translate(0, 0px);
+        opacity: 1;
+    }
+    to{
+        transform: translate(200px, 0px);
+        opacity: 0;
+    }
+    
+}
+@keyframes fadeAll {
+    from{
+        opacity: 1;
+    }
+    to{
+        opacity: 0;
+    }
+}
+</style>
+
+...
+
+```
+
+### Custom Overlay Transitions
+
+There are a few kinds of Custom Overlays
+
+OverlayCustom allows you to define which many different overlays and customize them. They will take the key as the class name (if you want to find it) and the value as the animation.
+
+After the object of divs, there is
+- duration
+- color of divs
+- timing
+- animation to play while Overlay Animation plays
+
+OverlayStyled is similar, except for two parts:
+- The object is now multi level, where the key is still the class name, but the value is object consisting of the animation name and the styles to be applied to the specific div.
+- After all the parameters, there is a new parameter that allows you to change the style of the blocker element. This is useful in cases like the example where since the div is a gradient, the blocker should look like that to be seamless
+
+```javascript
+let customOverlay = new OverlayCustom(
+    {
+        "first": "rise",
+        "second": "fall",
+        "third": "slide",
+        "fourth": "inverseSlide",
+    }, 3000, "#293241", "ease-in-out", null
+);
+
+let styledOverlay = new OverlayStyled(
+    {
+        "first": {
+            animationName: "rise",
+            cssDesign: {
+                "background": "linear-gradient(90deg,rgba(42, 123, 155, 1) 0%, rgba(87, 199, 133, 1) 50%, rgba(237, 221, 83, 1) 100%)"
+            }
+        }, 
+    }, 3000, "#293241", "ease-in-out", null, {
+            "background": "linear-gradient(90deg,rgba(42, 123, 155, 1) 0%, rgba(87, 199, 133, 1) 50%, rgba(237, 221, 83, 1) 100%)"
+    }
+)
+
+```
+
+#### Manual Transitions
+
+You can do transitions manually through the ```AnimatePageTransition(style)``` method which takes a Transitionstyle as a parameter
+
+
+### Custom Link function
+
+By default, this package uses a default function of ```window.location = link;``` for changing links. However, this can be customized in either ```SendPoint() or ListenForChange()```
+
+```
+let defaultAnimation = ...
+let linkFunction = (link) => {
+    console.log(link);
+    window.location = link;
+}
+SendPoint(defaultAnimation, linkFunction);
+```
+
+This is useful in SSR when the link change function is different from the default one.
+
+### Events
+
+There are many events that can be listened to to call certain code.
+
+- animateSF - animation start, forward direction
+- animateSR - animation start, reverse direction
+- animateEF - animation end, forward direction
+- animateER - animation end, reverse direction
+- animateSSP - start of Send Point listening (when a link is clicked)
+- animateESP - end of Send Point listen (when the animation is handled)
+- animateSEP - start of end point listen (when the load event is dispatched)
+- animateEEP - end of end point (when the page is revealed after an animation)
+- animateEPNA - end point no animation played (when the page is revealed but no animation was played)
+
+Listen by using window.addEventListener("...", (e) => {
+
+})
+
+### This program has optional parameters:
+
+#### Optional Parameter Name : Default Value
+
+```javascript
+//This is the class for the content that the transition will affect/cover
+mainContentIdName: "main-content"
+
+//This is the delay between the page loading and the page beginning the animation
+pageAnimationDelay: 100,
+
+//Whether the transition should run when the page is reloaded
+//Sometimes needs to be enabled in SSR because of how they treat going from one page to another as reloading
+runAnimationOnPageReload: false,
+
+//Whether the transition should run when a link goes to a different page
+runAnimationOnCrossSite: false,
+
+//The delay between the animation playing and the page revealing
+pageRevealDelay: 0,
+
+//Whether the page should be left after animation
+leavePageOnLink: true,
+
+//What the ID of the element that blocks the page is
+pageBlockerId: "pageBlocker",
+
+//What class should be added to links to not transition
+classToIgnoreLink: "ignore-click",
+
+//Whether ignored links should animate
+animateIgnoredLinks: false,
+
+//Whether links to the same page should animate
+animateSelfLink: true,
+
+//The event that is checked to see that the page is loaded and what CallEndPoint dispatches
+loadEvent: "DOMContentLoaded",
+
+// When true, it will ignore transitioning on a link if no animation is found in the class list
+// Otherwise, it will transition every time unless explicitly told to ignore
+preferIgnore: false
+```
+
+## Extending with Custom Transition classes
+PageWave provides many custom classes to create beautiful transitions:
+- **KeyFrameCustom** for a custom transition animation on main-content
+- **KeyFramePreset** to utilize premade animations for getting started quickly
+- **MultiElementAnimation** to animate multiple elements and have more fine grained control
+- **OverlayCustom** for a custom overlay animation
+- **OverlayPreset** to utilize premade overlay animations for getting started quickly
+- **OverlayStyled** to have complete control over how an overlay animation looks
+- **StyleTransition** to utilize the transition css property to animate a single property
+
+However, if you need to do something not listed here, the class system can be easily extended.
+
+To do so, you must implement the TransitionStyleInterface which requires a few parts to be defined:
+- duration: number (how long the animation lasts)
+- timing: TimingType (how the animation moves)
+- handle(direction: DirectionType, mainElement: HTMLElement) : void (runs the actual transition animation)
+- hidePage(options: OptionsType) : void (hides the page either before or after animation)
+- revealPage(options: OptionsType): void (reveals the page once animation needs to be shown)
+
+PageWave does the rest of the work on using these functions to create seamless transitions.
+
+If you want to use a preexisting implementation, you can use KeyFrameBase or OverlayBase which power many of their respective child classes.
+
+## Supporting
+
+If you find this project helpful, considering starring ⭐ it. I would greatly appreciate it! :)