├── .gitignore
├── .node-version
├── .npmignore
├── .prettierignore
├── .travis.yml
├── README.md
├── ava.config.js
├── lib
    └── sonar.js
├── media
    └── logomark.png
├── package-lock.json
├── package.json
└── test
    └── lib
        └── sonar-test.js


/.gitignore:
--------------------------------------------------------------------------------
1 | dist
2 | node_modules
3 | 


--------------------------------------------------------------------------------
/.node-version:
--------------------------------------------------------------------------------
1 | 11.6.0
2 | 


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | .eslintrc.js
3 | .nvmrc
4 | 


--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | README.md
2 | 


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | language: node_js
2 | node_js:
3 |   - "10"
4 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | <h1 align="center">
 2 | 	<br>
 3 | 	<img src="media/logomark.png" width="300px" alt="Sonar.js">
 4 | 	<br>
 5 | 	<br>
 6 |   Sonar.js
 7 | 	<br>
 8 | 	<br>
 9 | </h1>
10 | 
11 | [![](https://badgen.net/travis/brandonweiss/sonar-js?icon=travis)](https://www.travis-ci.com/brandonweiss/sonar-js)
12 | [![](https://badgen.net/npm/v/sonar-js?icon=npm)](https://www.npmjs.com/package/sonar-js)
13 | [![](https://badgen.net/david/dep/brandonweiss/sonar-js)](https://david-dm.org/brandonweiss/sonar-js)
14 | 
15 | > A tiny library for detecting when a browser is scrolled to the bottom of a web page.
16 | 
17 | You could use this, for example, on a blog to show a popover when a reader has finished a post, letting them know they can receive new posts by email if they submit their email address.
18 | 
19 | ## Installation
20 | 
21 | `yarn add sonar-js`
22 | 
23 | The package comes in three formats: CommonJS, Universal Module Definition, and ECMAScript Module.
24 | 
25 | | Format | package.json key | Path                     |
26 | |--------|------------------|--------------------------|
27 | | CJS    | main             | [dist/sonar.js][CJS]     |
28 | | UMD    | umd:main         | [dist/sonar.umd.js][UMD] |
29 | | ESM    | module           | [dist/sonar.m.js][ESM]   |
30 | 
31 | The package is built on-the-fly before publishing to NPM so the `dist` folder is not in the repo. Use the links above to get the built files.
32 | 
33 | ## Usage
34 | 
35 | Create an instance of `Sonar` passing in the `window` and then call `ping` passing in the range to the bottom of the page, a function to call when within range of the bottom and an optional function to call when not within range of the bottom.
36 | 
37 | When `ping` is called one of the callbacks will fire, depending on whether or not the scroll is currently within range of the page bottom. The behavior after that depends on which callbacks are provided.
38 | 
39 | ### One callback
40 | 
41 | ```javascript
42 | var sonar = new Sonar(window)
43 | 
44 | var withinRangeOfPageBottom = function() {
45 |   document.querySelector('.popover').classList.remove('hidden')
46 | }
47 | 
48 | sonar.ping(600, withinRangeOfPageBottom)
49 | ```
50 | 
51 | Without a second callback to fire when losing the bottom of the page this is essentially a one-time use. The callback will fire once when finding the bottom of the page and then never fire again, even if you scroll up and back down again.
52 | 
53 | This is useful for making a permanent change when someone scrolls to the bottom of the page.
54 | 
55 | ### Two callbacks
56 | 
57 | ```javascript
58 | var sonar = new Sonar(window)
59 | 
60 | var withinRangeOfPageBottom = function() {
61 |   document.querySelector('.popover').classList.remove('hidden')
62 | }
63 | 
64 | var notWithinRangeOfPageBottom = function() {
65 |   document.querySelector('.popover').classList.add('hidden')
66 | }
67 | 
68 | sonar.ping(600, withinRangeOfPageBottom, notWithinRangeOfPageBottom)
69 | ```
70 | 
71 | With a second callback to fire when losing the bottom of the page this becomes a toggle. The callbacks will only fire once when finding the bottom or losing the bottom. That is, the callbacks will only fire or re-fire when the state changes.
72 | 
73 | This is useful for making a temporary change when someone scrolls to the bottom of the page and then reversing it when they scroll away from the bottom of the page.
74 | 
75 | ## Tests
76 | 
77 | `yarn test`
78 | 
79 | ## Contributing
80 | 
81 | 1. Fork it ( https://github.com/brandonweiss/sonar-js/fork )
82 | 2. Create your feature branch (`git checkout -b my-new-feature`)
83 | 3. Commit your changes (`git commit -am "Add some feature"`)
84 | 4. Push to the branch (`git push origin my-new-feature`)
85 | 5. Create a new Pull Request
86 | 
87 | [CJS]: https://unpkg.com/sonar-js/dist/sonar.js
88 | [UMD]: https://unpkg.com/sonar-js/dist/sonar.umd.js
89 | [ESM]: https://unpkg.com/sonar-js/dist/sonar.m.js
90 | 


--------------------------------------------------------------------------------
/ava.config.js:
--------------------------------------------------------------------------------
1 | export default {
2 |   babel: true,
3 |   require: ["esm"],
4 | }
5 | 


--------------------------------------------------------------------------------
/lib/sonar.js:
--------------------------------------------------------------------------------
 1 | export default class Sonar {
 2 | 
 3 |   constructor(window) {
 4 |     this.window = window
 5 |     this.withinRangeOfPageBottom = undefined
 6 |   }
 7 | 
 8 |   ping(range, bottomFoundCallback, bottomLostCallback) {
 9 |     if (this._scroll) { return }
10 | 
11 |     this.withinRangeOfPageBottom = this._withinRangeOfPageBottom(range)
12 | 
13 |     if (this.withinRangeOfPageBottom) {
14 |       bottomFoundCallback()
15 | 
16 |       if (!bottomLostCallback) { return }
17 |     } else if (bottomLostCallback) {
18 |       bottomLostCallback()
19 |     }
20 | 
21 |     this._scroll = () => {
22 |       if (this._enteringRangeOfPageBottom(range)) {
23 |         this.withinRangeOfPageBottom = true
24 |         bottomFoundCallback()
25 | 
26 |         if (!bottomLostCallback) { this.stop() }
27 |       } else if (this._leavingRangeOfPageBottom(range)) {
28 |         this.withinRangeOfPageBottom = false
29 |         bottomLostCallback()
30 |       }
31 |     }
32 | 
33 |     this.window.addEventListener("scroll", this._scroll)
34 |   }
35 | 
36 |   stop() {
37 |     this.window.removeEventListener("scroll", this._scroll)
38 |     this._scroll = null
39 |   }
40 | 
41 |   _withinRangeOfPageBottom(range) {
42 |     return this._viewportBottomScrollPosition >= this._pageHeight - range
43 |   }
44 | 
45 |   _enteringRangeOfPageBottom(range) {
46 |     return this.withinRangeOfPageBottom === false && this._withinRangeOfPageBottom(range)
47 |   }
48 | 
49 |   _leavingRangeOfPageBottom(range) {
50 |     return this.withinRangeOfPageBottom === true && !this._withinRangeOfPageBottom(range)
51 |   }
52 | 
53 |   get _pageHeight() {
54 |     return this.window.document.body.offsetHeight
55 |   }
56 | 
57 |   get _viewportBottomScrollPosition() {
58 |     return this._viewportHeight + this._viewportTopScrollPosition
59 |   }
60 | 
61 |   get _viewportTopScrollPosition() {
62 |     return this.window.scrollY
63 |   }
64 | 
65 |   get _viewportHeight() {
66 |     return this.window.innerHeight
67 |   }
68 | 
69 | }
70 | 


--------------------------------------------------------------------------------
/media/logomark.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/brandonweiss/sonar-js/b767d739ce28f9a55a0021dab7371656fdfd97fd/media/logomark.png


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "sonar-js",
 3 |   "version": "1.1.0",
 4 |   "description": "A tiny library for detecting when a browser is scrolled to the bottom of a web page.",
 5 |   "main": "dist/sonar.js",
 6 |   "umd:main": "dist/sonar.umd.js",
 7 |   "module": "dist/sonar.mjs",
 8 |   "scripts": {
 9 |     "build": "microbundle --entry lib/sonar.js --name Sonar",
10 |     "prepublish": "npm run build",
11 |     "test": "ava",
12 |     "test:watch": "ava --watch"
13 |   },
14 |   "author": {
15 |     "name": "Brandon Weiss",
16 |     "email": "desk@brandonweiss.me",
17 |     "url": "http://brandonweiss.me"
18 |   },
19 |   "license": "ISC",
20 |   "repository": {
21 |     "type": "git",
22 |     "url": "https://github.com/brandonweiss/sonar-js.git"
23 |   },
24 |   "devDependencies": {
25 |     "@ava/babel": "^1.0.1",
26 |     "ava": "^3.5.1",
27 |     "esm": "^3.2.25",
28 |     "husky": "^4.2.3",
29 |     "jsdom": "^16.2.1",
30 |     "microbundle": "^0.11.0",
31 |     "np": "^6.2.0",
32 |     "prettier": "^2.0.2",
33 |     "pretty-quick": "^2.0.1"
34 |   },
35 |   "dependencies": {},
36 |   "husky": {
37 |     "hooks": {
38 |       "pre-commit": "pretty-quick --staged"
39 |     }
40 |   },
41 |   "prettier": {
42 |     "arrowParens": "always",
43 |     "printWidth": 100,
44 |     "semi": false,
45 |     "trailingComma": "all"
46 |   }
47 | }
48 | 


--------------------------------------------------------------------------------
/test/lib/sonar-test.js:
--------------------------------------------------------------------------------
  1 | import test from "ava"
  2 | import { JSDOM } from "jsdom"
  3 | import Sonar from "../../lib/sonar"
  4 | 
  5 | let createWindow = (options = {}) => {
  6 |   let dom = new JSDOM("<html><body></body></html>")
  7 |   let window = dom.window
  8 | 
  9 |   Object.defineProperties(window.HTMLElement.prototype, {
 10 |     offsetHeight: {
 11 |       get: () => options.pageHeight
 12 |     },
 13 |   })
 14 | 
 15 |   window.innerHeight = options.windowHeight
 16 | 
 17 |   return window
 18 | }
 19 | 
 20 | let scrollTo = (window, scrollY) => {
 21 |   window.scrollY = scrollY
 22 |   let event = new window.Event("scroll")
 23 |   window.dispatchEvent(event)
 24 | }
 25 | 
 26 | test("fires the entering callback when entering range of the bottom", (t) => {
 27 |   t.plan(1)
 28 | 
 29 |   let window = createWindow({
 30 |     pageHeight: 400,
 31 |     windowHeight: 200
 32 |   })
 33 | 
 34 |   let sonar = new Sonar(window)
 35 | 
 36 |   sonar.ping(100, () => {
 37 |     t.pass()
 38 |   })
 39 | 
 40 |   scrollTo(window, 0)
 41 |   scrollTo(window, 300)
 42 | })
 43 | 
 44 | test("fires the leaving callback when leaving range of the bottom", (t) => {
 45 |   t.plan(2)
 46 | 
 47 |   let window = createWindow({
 48 |     pageHeight: 400,
 49 |     windowHeight: 200
 50 |   })
 51 | 
 52 |   scrollTo(window, 300)
 53 | 
 54 |   let sonar = new Sonar(window)
 55 | 
 56 |   sonar.ping(100, () => {
 57 |     t.pass()
 58 |   }, () => {
 59 |     t.pass()
 60 |   })
 61 | 
 62 |   scrollTo(window, 0)
 63 | })
 64 | 
 65 | test("should only fire the entering callback once when within range of the page bottom", (t) => {
 66 |   t.plan(1)
 67 | 
 68 |   let window = createWindow({
 69 |     pageHeight: 400,
 70 |     windowHeight: 200
 71 |   })
 72 | 
 73 |   scrollTo(window, 0)
 74 | 
 75 |   let sonar = new Sonar(window)
 76 | 
 77 |   sonar.ping(100, () => {
 78 |     t.pass()
 79 |   })
 80 | 
 81 |   scrollTo(window, 300)
 82 |   scrollTo(window, 350)
 83 | })
 84 | 
 85 | test("should only fire the leaving callback once when not within range of the page bottom", (t) => {
 86 |   t.plan(1)
 87 | 
 88 |   let window = createWindow({
 89 |     pageHeight: 400,
 90 |     windowHeight: 200
 91 |   })
 92 | 
 93 |   scrollTo(window, 300)
 94 | 
 95 |   let sonar = new Sonar(window)
 96 | 
 97 |   sonar.ping(100, () => {}, () => {
 98 |     t.pass()
 99 |   })
100 | 
101 |   scrollTo(window, 0)
102 |   scrollTo(window, 0)
103 | })
104 | 
105 | test("fires the entering callback if already within range of the bottom when setup", (t) => {
106 |   t.plan(1)
107 | 
108 |   let window = createWindow({
109 |     pageHeight: 400,
110 |     windowHeight: 200
111 |   })
112 | 
113 |   scrollTo(window, 300)
114 | 
115 |   let sonar = new Sonar(window)
116 | 
117 |   sonar.ping(100, () => {
118 |     t.pass()
119 |   })
120 | })
121 | 
122 | test("fires the leaving callback if already not within range of the bottom when setup", (t) => {
123 |   t.plan(1)
124 | 
125 |   let window = createWindow({
126 |     pageHeight: 400,
127 |     windowHeight: 200
128 |   })
129 | 
130 |   scrollTo(window, 0)
131 | 
132 |   let sonar = new Sonar(window)
133 | 
134 |   sonar.ping(100, () => {}, () => {
135 |     t.pass()
136 |   })
137 | })
138 | 
139 | test("if there is no leaving callback when leaving and re-entering the entering callback will never fire again", (t) => {
140 |   t.plan(1)
141 | 
142 |   let window = createWindow({
143 |     pageHeight: 400,
144 |     windowHeight: 200
145 |   })
146 | 
147 |   scrollTo(window, 0)
148 | 
149 |   let sonar = new Sonar(window)
150 | 
151 |   sonar.ping(100, () => {
152 |     t.pass()
153 |   })
154 | 
155 |   scrollTo(window, 300)
156 |   scrollTo(window, 0)
157 |   scrollTo(window, 300)
158 | })
159 | 
160 | test("if starting within range of page bottom with no leaving callback the entering callback should fire and then never fire again", (t) => {
161 |   t.plan(1)
162 | 
163 |   let window = createWindow({
164 |     pageHeight: 400,
165 |     windowHeight: 200
166 |   })
167 | 
168 |   scrollTo(window, 300)
169 | 
170 |   let sonar = new Sonar(window)
171 | 
172 |   sonar.ping(100, () => {
173 |     t.pass()
174 |   })
175 | 
176 |   scrollTo(window, 0)
177 |   scrollTo(window, 300)
178 | })
179 | 


--------------------------------------------------------------------------------