feat: method to disable the Parallax Controller #13

Author: jscottsmith

documentation/docs/api/parallax-controller/index.md

@@ -22,7 +22,7 @@ See the options for creating a new controller tied to a view: [`ParallaxControll
 - [`removeElementById()`](./methods#removeelementbyid)
 - [`resetElementStyles()`](./methods#resetelementstyles)
 - [`updateScrollContainer()`](./methods#updatescrollcontainer)
-- [`disableAllElements()`](./methods#disableallelements)
-- [`enableAllElements()`](./methods#enableallelements)
+- [`disableParallaxController()`](./methods#disableParallaxController)
+- [`enableParallaxController()`](./methods#enableParallaxController)
 - [`update()`](./methods#update)
 - [`destroy()`](./methods#destroy)

documentation/docs/api/parallax-controller/init.md

@@ -25,4 +25,5 @@ The following option can be passed to `ParallaxController.init(...)`.
 | Option            |   Default    | Description                                                                |
 | ----------------- | :----------: | -------------------------------------------------------------------------- |
 | `scrollAxis`      | `'vertical'` | Direction of scroll for the element. One of `'vertical'` or `'horizontal'` |
+| `disabled`        |    false     | Initial disabled state of the Parallax Controller                          |
 | `scrollContainer` |   `window`   | HTMLElement that will contain scroll elements.                             |

documentation/docs/api/parallax-controller/methods.md

@@ -56,20 +56,20 @@ const el = document.getElementById('your-scroll-container');
 parallaxController.updateScrollContainer(el);
 ```
 
-## disableAllElements()
+## disableParallaxController()
 
-Disables all parallax elements in the controller.
+Disables the Parallax Controller.
 
 ```ts
-parallaxController.disableAllElements();
+parallaxController.disableParallaxController();
 ```
 
-## enableAllElements()
+## enableParallaxController()
 
-Enables all parallax elements in the controller.
+Enables the Parallax Controller.
 
 ```ts
-parallaxController.enableAllElements();
+parallaxController.enableParallaxController();
 ```
 
 ## update()

src/classes/Element.ts

@@ -27,14 +27,18 @@ import { scaleTranslateEffectsForSlowerScroll } from '../helpers/scaleTranslateE
 import { getShouldScaleTranslateEffects } from '../helpers/getShouldScaleTranslateEffects';
 import { clamp } from '../helpers/clamp';
 
-type ElementConstructorOptions = CreateElementOptions & {
+type ParallaxControllerConstructorOptions = {
   scrollAxis: ValidScrollAxis;
+  disabledParallaxController?: boolean;
 };
+type ElementConstructorOptions = CreateElementOptions &
+  ParallaxControllerConstructorOptions;
 
 export class Element {
   el: HTMLElement;
   props: ParallaxElementConfig;
   scrollAxis: ValidScrollAxis;
+  disabledParallaxController: boolean;
   id: number;
   effects: ParallaxStartEndEffects;
   isInView: boolean | null;
@@ -49,6 +53,8 @@ export class Element {
     this.el = options.el;
     this.props = options.props;
     this.scrollAxis = options.scrollAxis;
+    this.disabledParallaxController =
+      options.disabledParallaxController || false;
     this.id = createId();
     this.effects = parseElementTransitionEffects(this.props, this.scrollAxis);
     this.isInView = null;
@@ -150,7 +156,7 @@ export class Element {
   }
 
   _setElementStyles() {
-    if (this.props.disabled) return;
+    if (this.props.disabled || this.disabledParallaxController) return;
     const effects = this.scaledEffects || this.effects;
     setElementStyles(effects, this.progress, this.el);
   }
@@ -165,6 +171,12 @@ export class Element {
     this.easing = createEasingFunction(easing);
   }
 
+  updateElementOptions(options: ParallaxControllerConstructorOptions) {
+    this.scrollAxis = options.scrollAxis;
+    this.disabledParallaxController =
+      options.disabledParallaxController || false;
+  }
+
   updatePosition(scroll: Scroll): Element {
     if (!this.limits) return this;
 

src/classes/ParallaxController.test.ts

@@ -3,6 +3,7 @@ import { Element } from './Element';
 import { Rect } from './Rect';
 import { Limits } from './Limits';
 import { CSSEffect, ScrollAxis } from '../types';
+import * as elementStyles from '../helpers/elementStyles';
 
 const addEventListener = window.addEventListener;
 const removeEventListener = window.removeEventListener;
@@ -18,10 +19,45 @@ const OPTIONS = {
 
 describe('Expect the ParallaxController', () => {
   afterEach(() => {
+    jest.restoreAllMocks();
     window.addEventListener = addEventListener;
     window.removeEventListener = removeEventListener;
   });
 
+  describe('when init with disabled configuration', () => {
+    it('to not add listeners when init', () => {
+      window.addEventListener = jest.fn();
+      const controller = ParallaxController.init({
+        scrollAxis: ScrollAxis.vertical,
+        disabled: true,
+      });
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[0]).toEqual(
+        expect.arrayContaining(['test', null, expect.any(Object)])
+      );
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[1]).toBeUndefined();
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[2]).toBeUndefined();
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[3]).toBeUndefined();
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[4]).toBeUndefined();
+      // @ts-expect-error
+      expect(window.addEventListener.mock.calls[5]).toBeUndefined();
+      controller.destroy();
+    });
+    it('to create an element with the disabledParallaxController property', () => {
+      const controller = ParallaxController.init({
+        scrollAxis: ScrollAxis.vertical,
+        disabled: true,
+      });
+      const element = controller.createElement(OPTIONS);
+      expect(element.disabledParallaxController).toBe(true);
+      controller.destroy();
+    });
+  });
+
   it('to return an instance on init', () => {
     const controller = ParallaxController.init({
       scrollAxis: ScrollAxis.vertical,
@@ -62,6 +98,49 @@ describe('Expect the ParallaxController', () => {
     controller.destroy();
   });
 
+  describe('when disabling the controller', () => {
+    it('to update the disabled property', () => {
+      const controller = ParallaxController.init({
+        scrollAxis: ScrollAxis.vertical,
+      });
+      controller.disableParallaxController();
+      expect(controller.disabled).toBe(true);
+      controller.destroy();
+    });
+
+    it('to reset element styles', () => {
+      const controller = ParallaxController.init({
+        scrollAxis: ScrollAxis.vertical,
+      });
+      const element = controller.createElement(OPTIONS);
+      jest.spyOn(elementStyles, 'resetStyles');
+      controller.disableParallaxController();
+      expect(elementStyles.resetStyles).toHaveBeenCalledWith(element);
+      controller.destroy();
+    });
+
+    it('to remove listeners', () => {
+      window.removeEventListener = jest.fn();
+      const controller = ParallaxController.init({
+        scrollAxis: ScrollAxis.vertical,
+      });
+      controller.disableParallaxController();
+      // @ts-expect-error
+      expect(window.removeEventListener.mock.calls[0]).toEqual(
+        expect.arrayContaining(['test', null, expect.any(Object)])
+      );
+      // @ts-expect-error
+      expect(window.removeEventListener.mock.calls[1]).toEqual(
+        expect.arrayContaining(['scroll', expect.any(Function), false])
+      );
+      // @ts-expect-error
+      expect(window.removeEventListener.mock.calls[2]).toEqual(
+        expect.arrayContaining(['resize', expect.any(Function), false])
+      );
+      controller.destroy();
+    });
+  });
+
   it('to add a resize observer', () => {
     const controller = ParallaxController.init({
       scrollAxis: ScrollAxis.vertical,
@@ -129,6 +208,7 @@ describe('Expect the ParallaxController', () => {
   });
 
   it('to disable all elements when calling disableAllElements()', () => {
+    jest.spyOn(console, 'warn').mockImplementation(() => {});
     const controller = ParallaxController.init({
       scrollAxis: ScrollAxis.vertical,
     });
@@ -142,9 +222,13 @@ describe('Expect the ParallaxController', () => {
     elements.forEach(element => {
       expect(element.props.disabled).toBe(true);
     });
+    expect(console.warn).toHaveBeenCalledWith(
+      'deprecated: use disableParallaxController() instead'
+    );
   });
 
   it('to enable all elements when calling enableAllElements()', () => {
+    jest.spyOn(console, 'warn').mockImplementation(() => {});
     const controller = ParallaxController.init({
       scrollAxis: ScrollAxis.vertical,
     });
@@ -158,6 +242,9 @@ describe('Expect the ParallaxController', () => {
     elements.forEach(element => {
       expect(element.props.disabled).toBe(false);
     });
+    expect(console.warn).toHaveBeenCalledWith(
+      'deprecated: use enableParallaxController() instead'
+    );
   });
 
   it('to remove listeners when destroyed', () => {

src/classes/ParallaxController.ts

@@ -22,6 +22,7 @@ import {
  */
 
 export class ParallaxController {
+  disabled: boolean;
   elements: Element[];
   scrollAxis: ValidScrollAxis;
   viewEl: ViewElement;
@@ -51,7 +52,9 @@ export class ParallaxController {
   constructor({
     scrollAxis = ScrollAxis.vertical,
     scrollContainer,
+    disabled = false,
   }: ParallaxControllerOptions) {
+    this.disabled = disabled;
     this.scrollAxis = scrollAxis;
     // All parallax elements to be updated
     this.elements = [];
@@ -79,6 +82,10 @@ export class ParallaxController {
 
     // Bind methods to class
     this._bindAllMethods();
+
+    // If this is initialized disabled, don't do anything below.
+    if (this.disabled) return;
+
     this._addListeners(this.viewEl);
     this._addResizeObserver();
     this._setViewSize();
@@ -211,7 +218,7 @@ export class ParallaxController {
    * attributes, if so set the elements parallax styles.
    */
   _updateElementPosition(element: Element) {
-    if (element.props.disabled) return;
+    if (element.props.disabled || this.disabled) return;
     element.updatePosition(this.scroll);
   }
 
@@ -285,6 +292,7 @@ export class ParallaxController {
     const newElement = new Element({
       ...options,
       scrollAxis: this.scrollAxis,
+      disabledParallaxController: this.disabled,
     });
     newElement.setCachedAttributes(this.view, this.scroll);
     this.elements = this.elements
@@ -365,10 +373,37 @@ export class ParallaxController {
     this._updateAllElements({ updateCache: true });
   }
 
+  disableParallaxController() {
+    this.disabled = true;
+    // remove listeners
+    this._removeListeners(this.viewEl);
+    // reset all styles
+    if (this.elements) {
+      this.elements.forEach(element => resetStyles(element));
+    }
+  }
+
+  enableParallaxController() {
+    this.disabled = false;
+    if (this.elements) {
+      this.elements.forEach(element =>
+        element.updateElementOptions({
+          disabledParallaxController: false,
+          scrollAxis: this.scrollAxis,
+        })
+      );
+    }
+    // add back listeners
+    this._addListeners(this.viewEl);
+    this._addResizeObserver();
+    this._setViewSize();
+  }
+
   /**
    * Disable all parallax elements
    */
   disableAllElements() {
+    console.warn('deprecated: use disableParallaxController() instead');
     if (this.elements) {
       this.elements = this.elements.map(el => {
         return el.updateProps({ disabled: true });
@@ -381,6 +416,7 @@ export class ParallaxController {
    * Enable all parallax elements
    */
   enableAllElements() {
+    console.warn('deprecated: use enableParallaxController() instead');
     if (this.elements) {
       this.elements = this.elements.map(el => {
         return el.updateProps({ disabled: false });

src/types.ts

@@ -77,6 +77,7 @@ export type ViewElement = HTMLElement | Window;
 export type ParallaxControllerOptions = {
   scrollAxis?: ValidScrollAxis;
   scrollContainer?: HTMLElement;
+  disabled?: boolean;
 };
 
 export type EffectNumber = [number, number, EasingParam?];