withinviewport - npm Package Compare versions

Comparing version 2.1.2 to 3.0.0

package.json

 {
     "name": "withinviewport",
-    "version": "2.1.2",
     "description": "Determine whether an element is completely within the browser viewport",
-    "main": "withinviewport.js",
-    "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
+    "version": "3.0.0",
+    "type": "module",
     "repository": {
@@ -13,3 +10,45 @@ "type": "git",
     },
+    "devDependencies": {
+        "@testing-library/dom": "^8.19.1",
+        "@testing-library/jest-dom": "^5.16.5",
+        "@types/lodash": "^4.14.191",
+        "eslint-config-prettier": "^8.6.0",
+        "eslint-plugin-cypress": "^2.12.1",
+        "eslint-plugin-jest-dom": "^4.0.3",
+        "jest": "^29.3.1",
+        "jest-environment-jsdom": "^29.3.1"
+    },
+    "dependencies": {
+        "lodash": "^4.17.21"
+    },
+    "bugs": {
+        "url": "https://github.com/patik/within-viewport/issues"
+    },
+    "homepage": "https://github.com/patik/within-viewport",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "./dist/"
+    ],
+    "scripts": {
+        "build": "rm -rf dist/* && yarn tsc --project ./tsconfig.export.json && cp ../README.md ./README.md && cp ../LICENSE ./LICENSE",
+        "clean": "git clean -fdx",
+        "cover": "yarn test --collectCoverage",
+        "typecheck": "tsc --noEmit",
+        "code-lint": "eslint --ext .ts --fix ./src/**/*.ts",
+        "lint": "yarn typecheck && yarn code-lint && yarn unused-exports",
+        "preversion": "yarn build && yarn cover",
+        "test": "yarn jest --coverage",
+        "unused-exports": "ts-prune -p ./tsconfig.json",
+        "cypress:open": "cypress open"
+    },
     "keywords": [
+        "viewport",
+        "IntersectionObserver",
+        "window",
+        "DOM",
+        "visible",
+        "visibility",
+        "element",
+        "view",
         "within-viewport",
@@ -20,13 +59,16 @@ "browser",
         "infinite-scroll",
-        "scroll",
-        "view",
-        "viewport",
-        "window"
+        "scroll"
     ],
-    "author": "Craig Patik <[e-mail]> (http://patik.com)",
-    "license": "ISC",
-    "bugs": {
-        "url": "https://github.com/patik/within-viewport/issues"
+    "author": {
+        "name": "Craig Patik",
+        "email": "[e-mail]",
+        "url": "https://patik.com"
     },
-    "homepage": "http://patik.github.io/within-viewport"
+    "license": "BSD-3-Clause",
+    "lint-staged": {
+        "*.ts": "eslint --cache --cache-location .eslintcache --fix"
+    },
+    "engines": {
+        "node": ">=12.0"
+    }
 }

README.md

 # Within Viewport
 
-***Determine whether elements are within the viewport***
+***Determine whether elements are completely within the viewport***
 
 Includes:
 
-- A standalone, plain JavaScript function, `withinviewport()`
-- AMD and Node/CommonJS support
+- The synchronous function, `withinViewport()`
+  - Continues to support [legacy browsers](#browser-support)
+- The asynchronous, promise-based function, `withinViewportAsync()`
+  - More performant, but only for [modern browsers](https://caniuse.com/intersectionobserver) (e.g. post IE 11)
 - Optional jQuery plugin with handy selectors and shorthand methods
@@ -13,36 +15,18 @@
 
-## Note
+## Install
 
-Although this plugin is still actively maintained, it will eventually be made obsolete by the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). You can check the current state of browser compatibility at [caniuse.com](https://caniuse.com/#feat=intersectionobserver). Meanwhile, withinviewport will continue to work on current and [legacy browsers](#Browser-Support).
+```sh
+yarn add withinviewport
+```
 
-## Installation
+or
 
-### AMD, Node.js, CommonJS
-
-#### [NPM](https://www.npmjs.com/package/withinviewport)
-
-`npm install withinviewport`
-
-And then:
-
-`var withinviewport = require('withinviewport');`
-
-#### Bower:
-
-`bower install within-viewport`
-
-### Traditional include
-
-Standalone (no jQuery):
-
-```js
-<script src="withinviewport.js"></script>
+```sh
+npm install withinviewport
 ```
 
-jQuery plugin:
+And then in your JavaScript or TypeScript:
 
 ```js
-<script src="withinviewport.js"></script>
-<script src="jquery.js"></script>
-<script src="jquery.withinviewport.js"></script>
+import { withinViewport /* or withinViewportAsync */ } from 'withinviewport'
 ```
@@ -56,4 +40,6 @@
 // Returns true if the element is entirely within view of the window
-var elem = document.getElementById('#myElement');
-withinviewport(elem);
+const elem = document.getElementById('#myElement')
+
+withinViewport(elem) // returns a boolean
+withinViewportAsync(elem) // returns a Promise<boolean>
 ```
@@ -63,5 +49,7 @@
 
+All options work the same for both the synchronous and asynchronous functions.
+
 ```js
 // Test against only some sides of the window for faster performance
-withinviewport(elem, {sides: 'left'});
+withinViewport(elem, { left: 'ignore' })
 ```
@@ -71,3 +59,3 @@
 // Pick another element to act as the viewport (instead of `window`)
-withinviewport(elem, {container: document.getElementById('myElem')});
+withinViewport(elem, { container: document.getElementById('myElem') })
 ```
@@ -78,6 +66,6 @@
 // Example: element is at least 12px inside the top and right of the viewport
-withinviewport(elem, {top: 12, right: 12});
+withinViewport(elem, { top: 12, right: 12 })
 ```
 
-For more options, see [Settings](#settings) section below.
+For more options, see [Options](#options) section below.
 
@@ -87,5 +75,5 @@ ### Shorthand notation
 ```js
-// These will use the default thresholds; see 'Settings' section below
-withinviewport(elem, 'bottom right');
-withinviewport.left(elem);
+// This will only check the bottom and right of the viewport, ignoring the top and left
+withinViewport(elem, 'bottom right')
+left(elem)
 ```
@@ -95,9 +83,15 @@
 
-### Usage
+Be sure to include the full version of the script as well
 
-#### Basic
+```js
+<script src="withinviewport.js"></script>
+<script src="jquery.js"></script>
+<script src="jquery.withinviewport.js"></script>
+```
 
+### Basic usage
+
 ```js
 // Returns true if the element is entirely within the viewport
-$('#myElement').is(':within-viewport');
+$('#myElement').is(':within-viewport')
 ```
@@ -107,6 +101,6 @@
 // Returns a jQuery object of all <div>s that are within the viewport
-$('div').withinviewport();
+$('div').withinViewport()
 ```
 
-#### Advanced
+### Advanced usage
 
@@ -118,3 +112,3 @@ There are shorthand selectors and methods for testing against only one edge of the viewport.
 // Also works with 'top', 'right', and 'bottom'
-$('#myElement').is(':within-viewport-left');
+$('#myElement').is(':within-viewport-left')
 ```
@@ -124,3 +118,3 @@
 // Returns a jQuery collection of all <div>s within the left edge of the viewport
-$('div').withinviewportleft();
+$('div').withinViewportLeft()
 ```
@@ -130,3 +124,3 @@
 // Same as above, but only elements that are at least 12px inside the left edge
-$('div').withinviewportleft({left: 12});
+$('div').withinViewportLeft({ left: 12 })
 ```
@@ -138,6 +132,6 @@
 
-If you're looking to keep tabs on elements' whereabouts at all times, you can bind to the `window`'s `resize` and `scroll` events. Instead of `scroll`, I recommend using [James Padolsey's `scrollStop` event](http://james.padolsey.com/javascript/special-scroll-events-for-jquery/) since firing on every `window.scroll` event will [bring your UI to its knees](http://ejohn.org/blog/learning-from-twitter/).
+If you're looking to keep tabs on elements' whereabouts at all times, you can bind to the `window`'s `resize` and `scroll` events. However, for performance reasons, it's strongly recommended to [throttle](https://lodash.com/docs/#throttle) your event listener or use something like [James Padolsey's `scrollStop` event](https://web.archive.org/web/20210824132834/https://j11y.io/javascript/special-scroll-events-for-jquery/). Firing on every `window.scroll` event will [bring your UI to its knees](https://ejohn.org/blog/learning-from-twitter/).
 
 ```js
-$(window).on('resize scrollStop', function() {
+$(window).on('resize scrollStop', _.throttle(function() {
     // Your code here...
@@ -148,25 +142,21 @@
         // Momentarily declare all divs out of the viewport...
-        .removeClass('within-viewport');
+        .removeClass('within-viewport')
         // Then filter them to reveal which ones are still within it
         .filter(':within-viewport')
-            .addClass('within-viewport');
-});
+            .addClass('within-viewport')
+}, 100));
 ```
 
-A future version will allow you to fire custom events when elements pass in and out of the viewport.
+## Options
 
-## Settings
+All options work the same across the synchronous and asynchronous functions and the jQuery plugin.
 
-This applies to both the jQuery plugin and standalone function.
-
-Use the object `withinviewport.defaults` to define your page's practical viewport compared to the actual browser window.
-
 ### Custom viewport element
 
-If you want to test whether an element is within a scrollable parent element (e.g. which has `overflow: auto`), assign the parent element to the `container` property:
+If you want to test whether an element is within a scrollable parent element (e.g. which has `overflow: auto` or `scroll`), assign the parent element to the `container` property:
 
 ```js
-$('.child-element').withinviewport({
-    container: $('.parent-element')
-});
+withinViewport(elem, {
+    container: document.querySelector('.parent-element')
+})
 ```
@@ -179,3 +169,3 @@
 ```js
-withinviewport.defaults.top = 100;
+withinViewport(elem, { top: 100 })
 ```
@@ -186,35 +176,38 @@
 ```js
-withinviewport.defaults.sides = 'left bottom';
+withinViewport(elem, 'left bottom')
 ```
 
-You can also pass settings on the fly to temporarily override the defaults:
+You can also combine optins:
 
 ```js
-withinviewport(elem, {sides:'left bottom', left: 40});
-$('div').withinviewport({sides:'left bottom', left: 40});
+withinViewport(elem, { left: 40, container: myDiv })
+$('div').withinViewport({ right: -70, top: 'ignore' })
 ```
 
-Individual elements may have their own settings embedded in a `data` attribute using object notation. These will override both the defaults any any settings passed to the function on the fly (like the example above).
+You can specify *negative threshold values* to allow elements to reside outside the viewport.
 
-```html
-<div data-withinviewport-settings="{sides: 'left', top: 40}">
+## Migrating from v2 to v3
+
+The `sides` option has been deprecated. The following calls are equivalent:
+
+```js
+// 2.x: specifying which sides to *monitor*
+withinViewport(elem, { sides: ['left', 'right']})
+
+// 3.x: specifying which sides to *ignore*
+withinViewport(elem, { top: 'ignore', bottom: 'ignore' })
 ```
 
-You can specify *negative threshold values* to allow elements to reside outside the viewport.
-
 ## Browser Support
 
+For the synchronous functions:
+
 - IE 7(?) and higher
 - All the others except Opera Mini
-    + Tested in the latest stable Chrome, Firefox, Safari, and IE
-    + No "new" JavaScript or quirky techniques are employed so it should work in all other modern browsers not specifically mentioned above
+  - Tested in the latest stable Chrome, Firefox, Safari, and Edge
 
-## What's Next
+The asynchronous functions work in any browser that supports promises and [IntersectionObserver](https://caniuse.com/intersectionobserver).
 
-*Please note that the camel case `withinViewport` method name is deprecated and is no longer supported as of version 2.0.0.*
+All functions (both versions) are transpiled to ES5.
 
-- Option to **fire events** when elements pass in and out of the viewport
-- Test against Firefox 3.6, Safari 5.0.1
-
-
 ## Credit
@@ -224,11 +217,11 @@
 
-* Remy Sharp's [Element 'in view' Event Plugin](http://remysharp.com/2009/01/26/element-in-view-event-plugin/)
-* Mike Tuupola's [Viewport Selectors for jQuery](http://www.appelsiini.net/projects/viewport)
+- Remy Sharp's [Element 'in view' Event Plugin](https://remysharp.com/2009/01/26/element-in-view-event-plugin/)
+- Mike Tuupola's [Viewport Selectors for jQuery](https://github.com/tuupola/jquery_viewport)
 
 ## License
 
-Have fun with it &mdash; [ISC](http://choosealicense.com/licenses/isc/). See included [LICENSE](LICENSE) file.
+Have fun with it &mdash; [BSD-3-Clause](https://choosealicense.com/licenses/bsd-3-clause/). See included [LICENSE](LICENSE) file.
 
 ## Author
 
-Craig Patik, [patik.com](http://patik.com/) &amp; [@craigpatik](https://twitter.com/craigpatik)
+[Craig Patik](https://patik.com)

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

No tests

Quality

Package does not have any tests. This is a strong signal of a poorly maintained or low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

68116

increased by217.23%

Number of package files

43

increased by760%

Lines of code

871

increased by153.94%

Number of low quality alerts

0

decreased by-100%

Is type module

Yes

Worsened metrics

Dependency count

1

increased byInfinity%

Dev dependency count

8

increased byInfinity%

Number of lines in readme file

212

decreased by-3.2%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedlodash@^4.17.21

• + Addedlodash@4.17.21(transitive)