Medusa

A simple utility to easy handle multiple IntersectionObserver

Installation

# Install package
npm install @adoratorio/medusa

Browser Compatibility

If you want to support the browsers that don't support the Itersection Observer you have to change your idea or, at least, don't use this utils 🥳.

Usage

Since this package has a pkg.module field, it's highly recommended to import it as an ES6 module with some bundlers like webpack or rollup:

import Medusa from '@adoratorio/medusa';

const medusa = new Medusa(/* { ...medusaOptions  } */);

Available options

MedusaOptions

Definition:

| Parameter | Type | Default | Description | | :-------: | :--: | :-----: | :---------- | | observers | Array<ObserverConfig> | [] | Array to fill with observers custom configurations | | debug | boolean | false | Set it to true if you want messages in console |

Medusa observer

When you want to add a new observer in Medusa, you have to create a new configuration object with a specific structure where only the property id is required.

ObserverConfig interface:

interface ObserverConfig = {
  id : string,
  viewport : null | Document | HTMLElement,
  nodes : Array<Element>,
  threshold : number,
  offsets: string,
  emitGlobal : boolean,
  emitByNode : boolean,
  mode : MODE,
  callback : Function,
};

Definition:

| Parameter | Type | Default | Description | | :-------: | :--: | :-----: | :---------- | | id | string | required | The Observer identifier. | | viewport | HTMLElement | null | The element that is used as the viewport for checking visibility of the target.| | nodes | Array<Element> | [] | All nodes you want to observe. | | threshold | number | 0 | numbers which indicate at what percentage of the target's visibility, a float value between (0, 1).You can use:• a float number • Medusa.THRESHOLD.BEARLY (0.0)• Medusa.THRESHOLD.HALF (0.5)• Medusa.THRESHOLD.FULL (1.0) | | offsets | string | '0px 0px 0px 0px' | Margin around the root. Can have values similar to the CSS margin property | | emitGlobal | boolean | false | If it's true, Medusa emit the intersection custom event on the window | | emitByNode | boolean | false | If it's true, Medusa emit the intersection custom event on the node that intersect the viewport | | Mode | string | Meduse.MODE.DEFAULT | Parameter that permit to change how many time the callback is execute.You can use:• Medusa.MODE.DEFAULT or 'default': trigger the callback every time the element intersect the viewport threshold.Medusa.MODE.ONCE or 'once': trigger the callback the only once.Medusa.MODE.BYPIXELS or 'byPixel': trigger the callback every pixel when the element observed is in viewport. | | callback | function | (e, o) => {} | A function that is executed whenever an element intersect the viewport threshold that you set in the options. You have the access to the single entry and the istance of the observer. |

Properties

observers

You can access to all the observers added by the property observers.

Medusa.observers : Map<string, InternalObserver>;

If you want a specific InternalObserver you can do like this:

Medusa.observers.get('observerId');

ObserverConfig interface:

interface InternalObserver = {
  id : string,
  observerInstance : null | IntersectionObserver,
  observedNodes : Map<number, MedusaElement>,
  emitGlobal : boolean,
  emitByNode : boolean,
  mode : MODE,
  callback : Function,
};

InternalObserver definition:

| Parameter | Type | Description | | :-------: | :--: | :---------- | | id | string | The InternalObserver identifier. | | observerInstance | IntersectionObserver | The IntersectionObserver instance.| | observedNodes | Map<number, MedusaElement> | A Map of element observed by the IntersectionObserver. The number is the element unique id. | | emitGlobal | boolean | If it's true, Medusa emit the intersection custom event on the window | | emitByNode | boolean | If it's true, Medusa emit the intersection custom event on the node that intersect the viewport | | Mode | string | Parameter that permit to change how many time the callback is execute. | | callback | function | A function that is executed whenever an element intersect the viewport threshold that you set in the options. You have the access to the single entry and the istance of the observer. |

Methods

addObserver

To add a new observer you have to create a specific object with the ObserverConfig structure and then you have to pass it to the method.

Medusa.addObserver(configurations : Array<PartialObserverConfig> | PartialObserverConfig);

removeObserver

To remove a specific observer you have to know its id and then pass it to the method.

Medusa.removeObserver('observerId' : string);

clearObserver

Call it if you want to remove all observed nodes from a specific observer providing its id to the method.

Medusa.clearObserver('observerId' : string);

clearAllObservers

Call it if you want to remove all observed nodes from all observers.

Medusa.clearAllObservers();

observe

To observe single node or an array of nodes, you have to pass the observerId of the observer already created and the node/nodes that you want to add.

Medusa.observe('observerId' : string, elToAdd : Element | Array<Element>);

unobserve

To unobserve a single node or an array of nodes, you have to pass the observerId of the observer and the node/nodes that you want to remove.

Medusa.unobserve('observerId' : string, elToRemove : Element | Array<Element>);

Events

When a new Observer is created you can choose if Medusa can emit an event on two different targets:

| Event | Arguments | Description | | :---: | :-------: | :---------- | | medusa-${observerId} | event | If you set emitGlobal property to true will emit a golbal event on the window when the callback is triggered, on the other hand, if you set emitByNode property to true in the configuration object Medusa will emit an event on the IntersectionObserver entry.target. |

Argument details:

event.detail = {
  node : Element, // node observed that intersect the viewport previously defined
  isIn : boolean, // if the element observed is in viewport or not
  entry : IntersectionObserverEntry, // the IntersectionObserver entry
}