use-browser-history - npm Package Compare versions

Comparing version 0.0.1 to 1.0.0

dist/index.es.js

@@ -18,4 +18,23 @@ import { useEffect } from 'react';
 
-function useBrowserHistory(name, isOpen, onBack, onForward) {
+var _extends = Object.assign || function (target) {
+  for (var i = 1; i < arguments.length; i++) {
+    var source = arguments[i];
+
+    for (var key in source) {
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  return target;
+};
+
+function useBrowserHistory(name, isActive, onBack, onForward) {
+  /**
+   * Ensures the browser history state stays up to date for when the browser back button
+   * is pressed, and when the hook being called from inside a function component is fired.
+   */
   function handleBack() {
+    /* Force the browser to go back to remove the entry from the browser history state. */
     if (window.history.state && window.history.state[name]) {
@@ -25,2 +44,3 @@ window.history.go(-1);
 
+    /* Fire the optional callback for `onBack`. */
     if (onBack) {
@@ -31,3 +51,7 @@ onBack();
 
+  /**
+   * Handles the browser forward button being pressed. There's nothing to do internally here!
+   */
   function handleForward() {
+    /* Fire the optional callback for `onForward`. */
     if (onForward) {
@@ -38,3 +62,12 @@ onForward();
 
+  /**
+   * Handles the window event for `popstate` being fired.
+   * If our entry exists in the browser history state, we can assume the back button has been
+   * pressed. Otherwise, we can assume the forward button has been pressed.
+   *
+   * @param {{ state: {} }} event
+   */
   function handlePopState(event) {
+    /* If the entry doesn't exist, assume it has just been popped from the state (i.e. back
+      * button pressed). Otherwise, assume the opposite - i.e. forward button pressed. */
     if (!event.state || !event.state[name]) {
@@ -48,17 +81,29 @@ handleBack();
   useEffect(function () {
+    /* Add up the event listener. */
     window.addEventListener('popstate', handlePopState);
 
-    if (isOpen && (!window.history.state || !window.history.state[name])) {
-      window.history.pushState(defineProperty({}, name, true), '');
+    /* If `isActive` is set and we haven't made an entry to the browser history state yet,
+     * push our new entry onto the stack. From hereon, when the browser back button is pressed,
+     * the page won't change, and we can handle that event above to fire our internal functions. */
+    if (isActive && (!window.history.state || !window.history.state[name])) {
+      /* Push the new entry to the state, as well as any existing state in the browser history. */
+      window.history.pushState(_extends({}, window.history.state, defineProperty({}, name, true)), '');
     }
 
+    /* Perform clean up in here. */
     return function () {
+      /* Clean up the event listener. */
       window.removeEventListener('popstate', handlePopState);
 
-      if (isOpen) {
+      /* If `isActive` is set (and therefore means it is being changed to `false` on the next
+       * render), fire the `handleBack` function to clean up the browser history state. */
+      if (isActive) {
         handleBack();
       }
     };
-  }, [isOpen]);
+  }, [isActive]); // Only update when `isActive` changes
 
+  /* Provide these functions so the function component can integrate with the browser history.
+   * I couldn't think of a use-case for `handleForward` being called within the component, but
+   * it's provided just in case. */
   return [handleBack, handleForward];
@@ -65,0 +110,0 @@ }

dist/index.js

@@ -20,4 +20,23 @@ 'use strict';
 
-function useBrowserHistory(name, isOpen, onBack, onForward) {
+var _extends = Object.assign || function (target) {
+  for (var i = 1; i < arguments.length; i++) {
+    var source = arguments[i];
+
+    for (var key in source) {
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  return target;
+};
+
+function useBrowserHistory(name, isActive, onBack, onForward) {
+  /**
+   * Ensures the browser history state stays up to date for when the browser back button
+   * is pressed, and when the hook being called from inside a function component is fired.
+   */
   function handleBack() {
+    /* Force the browser to go back to remove the entry from the browser history state. */
     if (window.history.state && window.history.state[name]) {
@@ -27,2 +46,3 @@ window.history.go(-1);
 
+    /* Fire the optional callback for `onBack`. */
     if (onBack) {
@@ -33,3 +53,7 @@ onBack();
 
+  /**
+   * Handles the browser forward button being pressed. There's nothing to do internally here!
+   */
   function handleForward() {
+    /* Fire the optional callback for `onForward`. */
     if (onForward) {
@@ -40,3 +64,12 @@ onForward();
 
+  /**
+   * Handles the window event for `popstate` being fired.
+   * If our entry exists in the browser history state, we can assume the back button has been
+   * pressed. Otherwise, we can assume the forward button has been pressed.
+   *
+   * @param {{ state: {} }} event
+   */
   function handlePopState(event) {
+    /* If the entry doesn't exist, assume it has just been popped from the state (i.e. back
+      * button pressed). Otherwise, assume the opposite - i.e. forward button pressed. */
     if (!event.state || !event.state[name]) {
@@ -50,17 +83,29 @@ handleBack();
   react.useEffect(function () {
+    /* Add up the event listener. */
     window.addEventListener('popstate', handlePopState);
 
-    if (isOpen && (!window.history.state || !window.history.state[name])) {
-      window.history.pushState(defineProperty({}, name, true), '');
+    /* If `isActive` is set and we haven't made an entry to the browser history state yet,
+     * push our new entry onto the stack. From hereon, when the browser back button is pressed,
+     * the page won't change, and we can handle that event above to fire our internal functions. */
+    if (isActive && (!window.history.state || !window.history.state[name])) {
+      /* Push the new entry to the state, as well as any existing state in the browser history. */
+      window.history.pushState(_extends({}, window.history.state, defineProperty({}, name, true)), '');
     }
 
+    /* Perform clean up in here. */
     return function () {
+      /* Clean up the event listener. */
       window.removeEventListener('popstate', handlePopState);
 
-      if (isOpen) {
+      /* If `isActive` is set (and therefore means it is being changed to `false` on the next
+       * render), fire the `handleBack` function to clean up the browser history state. */
+      if (isActive) {
         handleBack();
       }
     };
-  }, [isOpen]);
+  }, [isActive]); // Only update when `isActive` changes
 
+  /* Provide these functions so the function component can integrate with the browser history.
+   * I couldn't think of a use-case for `handleForward` being called within the component, but
+   * it's provided just in case. */
   return [handleBack, handleForward];
@@ -67,0 +112,0 @@ }

package.json

 {
   "name": "use-browser-history",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "",
@@ -25,3 +25,2 @@ "author": "zcallan",
   "peerDependencies": {
-    "prop-types": "^15.5.4",
     "react": "^16.8.0"
@@ -28,0 +27,0 @@ },

README.md

 # use-browser-history
 
->
+> A React hook to handle browser history events
 
 [![NPM](https://img.shields.io/npm/v/use-browser-history.svg)](https://www.npmjs.com/package/use-browser-history) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 
+![](example.gif)
+
+https://zcallan.github.io/use-browser-history/
+
 ## Install
@@ -55,4 +59,17 @@
 
+## API
+
+```js
+const [handleBack, handleForward] = useBrowserHistory( name, isActive, onBack, onForward );
+```
+
+|Key | Type | Description |
+|----|------|----------|
+|name|`string`|**(required)** The unique name to be used inside the browser history state. |
+|isActive|`bool`|**(required)** Whether or not the entry should exist in the browser history state. *For example, in the case of a modal, this should be set to `true` when the modal is open / visible, and `false` when it's closed.*|
+|onBack|`func`|A callback that is fired when the back button is pressed, or when the `handleBack` (first arg returned by `useBrowserHistory`) function is called and the browser history state has been cleaned up.|
+|onForward|`func`|Exactly like `onBack`, but for the forward button. You can use this to re-perform something if the user clicks back then forward (like in the example GIF above), to do something such as re-opening a modal.|
+
 ## License
 
 MIT © [zcallan](https://github.com/zcallan)

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

19235

increased by100.89%

Dependency count

1

decreased by-50%

Lines of code

187

increased by81.55%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

75

increased by29.31%

No dependency changes