passive-events-support - npm Package Compare versions

Comparing version 1.0.19 to 1.0.20

package.json

 {
   "name": "passive-events-support",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Passive Events Support",
@@ -5,0 +5,0 @@ "main": "src/index.js",

README.md

@@ -5,23 +5,19 @@ # Passive Events Support
 
-How many times have you installed a library such as **Bootstrap**, **jQuery**, **Materialize CSS** or other and suddenly in the **Google Chrome** console you're prompted with a warning:
+How many times have you yourself forgotten to make an event listener as `passive`, or installed a library such as **Bootstrap**, **jQuery** or **Materialize** and suddenly in the **Google Chrome** console you're prompted a warning:
 
-> [Violation] Added non-passive event listener to a scroll-blocking 'touchstart' event. Consider marking event handler as 'passive' to make the page more responsive.
+> **[Violation]** Added non-passive event listener to a scroll-blocking `'touchstart'` event. Consider marking event handler as `passive` to make the page more responsive.
 
 Or when running **Lighthouse** you get a lower score with a message:
 
-> **Does not use passive listeners to improve scrolling performance**
+> Does not use passive listeners to improve scrolling performance
 >
-> Consider marking your touch and wheel event listeners as `passive` to improve your page's scroll performance.
+> Consider marking your `touch` and `wheel` event listeners as `passive` to improve your page's scroll performance.
 
-With many bad practice advices online, it is frustrating to find a proper solution that does not only hide the warnings, but also improves scrolling performance.
+Making event listeners as `passive` manually could be a repetetive and time consuming experience. Also if caused by a 3rd party, modifying its' source code should never be an option!
 
-Common suggestion is to modify 3rd party source code and assign `passive` option manually. Despite the fact that you should never modify 3rd party source code, searching event listeners and assigning certain `passive` value depending on `preventDefault()` usage is a time consuming experience.
+Here comes the **Passive Events Support**! This is the package that will help you debug the source, solve the issue, but also improve the performance. It is flexible and highly configurable package!
 
-Another suggestion is to apply `passive: false` to all the event listeners that cause the warning. The warning will be gone, but the performance will not be improved whatsoever. What's the point then? On the other side, blindly assigning `passive: true` to all the event listeners manually or with a package such as `default-passive-events` will lead you to nothing else but errors in case of `preventDefault()` usage.
-
-Here comes **Passive Events Support**. This is the package that will not only solve the issue, but also improve the performance.
-
 ## How it works
 
-When event listener does not have a `passive` option, it will be added and its value will depend on whether `preventDefault()` is called or not.
+When event listener does not have a `passive` option, it will be added and its value will depend on whether `preventDefault()` is being called in the handler or not.
 
@@ -58,17 +54,15 @@ When event listener is not calling `preventDefault()` and `passive` option is not passed, it will add a `{ passive: true }`
 
-### JS
-
 ```js
+// With JS
+import 'passive-events-support'
+// or
 require 'passive-events-support'
-// or
-import 'passive-events-support'
 ```
 
-### HTML
-
 ```html
+<!-- With HTML -->
 <script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
 ```
 
-By default, importing this package will automatically resolve the issue. The `passive` option will be assigned to all the listeners of these events:
+By default, importing this package will automatically make all the event listeners, for the events listed below, as passive.
 
@@ -81,25 +75,32 @@ | Type | Events |
 
-> **Warning!** It is highly recommended to pass only the elements and events that cause the issue to decrease the possibility of incompatibility. See the section below...
+While on small projects with no dependencies the default import might work like a charm, on a project with loaded 3rd parties, like **jQuery**, it might not work and cause some of the event listeners break. See the exact issues and how to fix it in the sections below.
 
+## Know Issues
+
+This package with its' default behaviour will check if `preventDefault()` is being called by the handler itself and make listener as passive if not. But what happens if the handler calls another method and only that method calls the `preventDefault()`? This event listener will break prompting an error message:
+
+> Unable to preventDefault inside passive event listener invocation.
+
+But don't worry! This can be debugged and easilly fixed by just configuring the package! See the **Customization** section below...
+
 ## Customization
 
-It is recommended to customize and only pass the elements and events that seems to trigger the warning. Sometimes the default installation might cause an issue for listeners that call `preventDefault()` way too deep in the handler. i.e. handler calls another method where `preventDefault()` is called... Some real life scenarios:
+It is highly recommended to customize and only pass the custom list of events, that seems to trigger the warning, and custom list of prevented event listeners, that should not be marked as passive.
 
-- For **Materialize CSS** just `touchstart`, `touchmove` and `touchend` were needed. It worked fine with all the default events tho.
-- For **jQuery** just `touchstart`, `touchmove` and `mousewheel` were needed. Depends on **jQuery** plugins in use (i.e. **Select2**).
-- For **Select2** just `touchstart` and `touchmove` were needed. It worked fine with all the default events except `touchstart`. See the **Debugging** section at the end to see how to find out which event is breaking for which element.
+But, how do I know which event listeners should I make as passive?
 
-### 1. Fixing certain events
+### 1. Debugging
 
-To customize the event list, you will need to pass an array of events manually:
+If you want to debug which event listeners are being updated, pass `true` as the second argument after the event list:
 
 ```js
+// With JS
 import { passiveSupport } from 'passive-events-support/src/utils'
-
-passiveSupport(['touchmove', 'mousewheel'])
+passiveSupport({ debug: true })
 ```
 
 ```html
+<!-- With HTML -->
 <script>
-  window.passiveEvents = ['touchmove', 'mousewheel']
+  window.passiveDebug = true // will console log updated event listeners
 </script>
@@ -109,44 +110,69 @@ <script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
 
-### 2. Ignoring certain elements
+### 2. Custom events
 
-### 3. Fixing certain event listeners
+**Real life scenario:**
+when using **Materialize**, even tho it works fine with the default event list, just `touchstart` and `touchmove` events are being used by **Materialize** to define non-passive event listeners.
 
-In case you want to add `passive` option manually to a certain event listener, use `passiveSupported($debug = false)` helper to find out if `passive` option is even supported by your browser:
+The solution would be to manually pass a custom event list:
 
 ```js
-import { passiveSupported } from 'passive-events-support/src/utils'
-
-element.addEventListener('touchstart', handler, passiveSupported() ? { passive: true } : false)
+// With JS
+import { passiveSupport } from 'passive-events-support/src/utils'
+passiveSupport({ events: ['touchstart', 'touchmove'] })
 ```
 
 ```html
-<script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
+<!-- With HTML -->
 <script>
-  element.addEventListener('touchstart', handler, window.passiveSupported ? { passive: true } : false)
+  window.passiveEvents = ['touchstart', 'touchmove']
 </script>
+<script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
 ```
 
-### 4. Debugging
+### 3. Prevented event listeners
 
-If you want to debug which event listeners are being updated, pass `true` as the second argument after the event list:
+**Real life scenario:**
+when using **jQuery** and **Select2** just `touchstart`, `touchmove` and `mousewheel` are being used to define non-passive event listeners. The `touchstart` event by **Select2** is used to define an event listener that actually does `preventDefault()`, but is not caught by default configuration, so the event listener is incorrectly being marked as passive causing the select element to break...
 
+To fix this issue we can manually pass the list of event listeners that should never be marked as passive:
+
 ```js
+// With JS
 import { passiveSupport } from 'passive-events-support/src/utils'
-
-$events = null // will use default list when null passed
-$debug = true // will console log updated event listeners
-passiveSupport($events, $debug)
+passiveSupport({
+  events: ['touchstart', 'touchmove', 'mousewheel'],
+  preventedListeners: [{
+    element: '.select-choice',
+    event: 'touchstart'
+  }]
+})
 ```
 
 ```html
+<!-- With HTML -->
 <script>
-  window.passiveDebug = true // will console log updated event listeners
+  window.passiveEvents = ['touchstart', 'touchmove', 'mousewheel']
+  window.passivePreventedListeners = [{
+    element: '.select-choice',
+    event: 'touchstart'
+  }]
 </script>
-<script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
 ```
 
-If this package breaks any component upon interaction, or you get such error like:
+### 4. Manually marking certain event listeners as passive
 
-> Unable to preventDefault inside passive event listener invocation.
+In case you want to add `passive` option manually to a certain event listener, use `passiveSupported($debug = false)` helper to find out if `passive` option is even supported by your browser:
 
-Enable debugging as shown in the **Customization** section above and find out which event is failing so you could remove it from the event list provided to `passiveSupport()`.
+```js
+// With JS
+import { passiveSupported } from 'passive-events-support/src/utils'
+element.addEventListener('touchstart', handler, passiveSupported() ? { passive: true } : false)
+```
+
+```html
+<!-- With HTML -->
+<script type="text/javascript" src="node_modules/passive-events-support/dist/main.js"></script>
+<script>
+  element.addEventListener('touchstart', handler, window.passiveSupported ? { passive: true } : false)
+</script>
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

13378

increased by2.74%

Number of lines in readme file

174

increased by17.57%

No dependency changes