remix-run · mjackson · Jun 12, 2020 · Nov 4, 2019 · Nov 4, 2019 · Nov 5, 2019
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,2 @@
+/build
+/fixtures
diff --git a/modules/.eslintrc → .eslintrc b/modules/.eslintrc → .eslintrc
@@ -1,15 +1,23 @@
 {
   "parser": "babel-eslint",
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module"
+  },
   "plugins": ["import"],
   "env": {
-    "browser": true
+    "node": true
   },
   "extends": ["eslint:recommended", "plugin:import/errors"],
   "rules": {
-    "prefer-arrow-callback": 2
-  },
-  "parserOptions": {
-    "ecmaVersion": 6,
-    "sourceType": "module"
+    "prefer-arrow-callback": "error",
+    "no-unused-vars": [
+      "warn",
+      {
+        "args": "after-used",
+        "ignoreRestSiblings": true,
+        "argsIgnorePattern": "event"
+      }
+    ]
   }
 }
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,4 @@
-/node_modules/
-/esm/
-/cjs/
-/umd/
-/local.log
+/build/
+/fixtures/*/history.js
+
+node_modules/
diff --git a/.size-snapshot.json b/.size-snapshot.json
diff --git a/.travis.yml b/.travis.yml
@@ -1,26 +1,26 @@
 language: node_js
 node_js: node
 cache: yarn
-env:
-- TEST_ENV=cjs BUILD_ENV=cjs
-- TEST_ENV=umd BUILD_ENV=umd
-- TEST_ENV=source
-before_script:
-- ([[ -z "$BUILD_ENV" ]] || yarn build)
-script:
-- yarn lint
-- yarn test
 jobs:
   include:
+  - stage: Test
+    before_script: yarn build
+    script: yarn test
+  - stage: Size
+    before_script: yarn build
+    script: yarn size
   - stage: Release
     if: tag =~ ^v[0-9]
     env: NPM_TAG=$([[ "$TRAVIS_TAG" == *-* ]] && echo "next" || echo "latest")
+    before_script: yarn build
     script: echo "Releasing $TRAVIS_TAG to npm with tag \"$NPM_TAG\" ..."
     deploy:
       provider: npm
-      skip_cleanup: true
-      tag: "$NPM_TAG"
+      edge: true
+      cleanup: false
       email: [email protected]
-      api_key: "$NPM_TOKEN"
+      api_token: "$NPM_TOKEN"
+      src: "./build/history"
+      tag: "$NPM_TAG"
       on:
         tags: true
diff --git a/DOMUtils.js b/DOMUtils.js
diff --git a/ExecutionEnvironment.js b/ExecutionEnvironment.js
diff --git a/LocationUtils.js b/LocationUtils.js
diff --git a/PathUtils.js b/PathUtils.js
diff --git a/createBrowserHistory.js b/createBrowserHistory.js
diff --git a/createHashHistory.js b/createHashHistory.js
diff --git a/createMemoryHistory.js b/createMemoryHistory.js
diff --git a/createTransitionManager.js b/createTransitionManager.js
diff --git a/docs/Blocking.md b/docs/Blocking.md
@@ -1,38 +1,31 @@
 # Blocking Transitions
 
-`history` lets you register a prompt message that will be shown to the user before location listeners are notified. This allows you to make sure the user wants to leave the current page before they navigate away.
+`history` lets you block navigation away from the current page so you can make sure e.g. the user wants to leave before they go to another page and possibly lose some changes they've made in the current page.
 
 ```js
-// Register a simple prompt message that will be shown the
-// user before they navigate away from the current page.
-const unblock = history.block('Are you sure you want to leave this page?');
-
-// Or use a function that returns the message when it's needed.
-history.block((location, action) => {
-  // The location and action arguments indicate the location
-  // we're transitioning to and how we're getting there.
-
-  // A common use case is to prevent the user from leaving the
-  // page if there's a form they haven't submitted yet.
-  if (input.value !== '') return 'Are you sure you want to leave this page?';
+// Block navigation and register a callback that
+// fires when a navigation attempt is blocked.
+let unblock = history.block(tx => {
+  // Navigation was blocked! Let's show a confirmation dialog
+  // so the user can decide if they actually want to navigate
+  // away and discard changes they've made in the current page.
+  let url = tx.location.pathnanme;
+  if (window.confirm(`Are you sure you want to go to ${url}?`)) {
+    // Unblock the navigation.
+    unblock();
+
+    // Retry the transition.
+    tx.retry();
+  }
 });
-
-// To stop blocking transitions, call the function returned from block().
-unblock();
 ```
 
-**Note:** You'll need to provide a `getUserConfirmation` function to use this feature with `createMemoryHistory` (see below).
+This example uses `window.confirm`, but you could also use your own custom confirm dialog if you'd rather.
 
-## Customizing the Confirm Dialog
+## Caveats
 
-By default, [`window.confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm) is used to show prompt messages to the user. If you need to override this behavior (or if you're using `createMemoryHistory`, which doesn't assume a DOM environment), provide a `getUserConfirmation` function when you create your history object.
+`history.block` will call your callback for all in-page navigation attempts, but for navigation that reloads the page (e.g. the refresh button or a link that doesn't use `history.push`) it registers [a `beforeunload` handler](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event) to prevent the navigation. In modern browsers you are not able to customize this dialog. Instead, you'll see something like this (Chrome):
 
-```js
-const history = createHistory({
-  getUserConfirmation(message, callback) {
-    // Show some custom dialog to the user and call
-    // callback(true) to continue the transiton, or
-    // callback(false) to abort it.
-  }
-});
-```
+![Chrome navigation confirm dialog](images/block.png)
+
+One subtle side effect of registering a `beforeunload` handler is that the page will not be [salvageable](https://html.spec.whatwg.org/#unloading-documents) in [the `pagehide` event](https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event).
diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
@@ -1,84 +1,84 @@
 # Intro
 
-The history library is a lightweight layer over browsers' built-in [History](https://developer.mozilla.org/en-US/docs/Web/API/History) and [Location](https://developer.mozilla.org/en-US/docs/Web/API/Location) APIs. The goal is not to provide a full implementation of these APIs, but rather to make it easy for users to opt-in to different methods of navigation.
+The history library provides history tracking and navigation primitives for JavaScript applications that run in browsers and other stateful environments.
 
-We provide 3 different methods for creating a `history` object, depending on the needs of your environment:
+We provide 3 different methods for working with history, depending on your environment:
 
-- `createBrowserHistory` is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history))
-- `createHashHistory` is for use in situations where you want to store the location in the [hash](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/hash) of the current URL to avoid sending it to the server when the page reloads
-- `createMemoryHistory` is used as a reference implementation and may also be used in non-DOM environments, like [React Native](https://facebook.github.io/react-native/) or tests
+- A "browser history" is for use in modern web browsers that support the [HTML5 history API](http://diveintohtml5.info/history.html) (see [cross-browser compatibility](http://caniuse.com/#feat=history))
+- A "hash history" is for use in web browsers where you want to store the location in the [hash](https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/hash) portion of the current URL to avoid sending it to the server when the page reloads
+- A "memory history" is used as a reference implementation that may be used in non-browser environments, like [React Native](https://facebook.github.io/react-native/) or tests
 
-Depending on the method you want to use to keep track of history, you'll `import` (or `require`, if you're using CommonJS) only one of these methods.
+Since you'll only ever need to use one in a given app, we provide environment-specific bundles. You'll need to `import` one of these bundles:
+
+- `history/browser`
+- `history/hash`
+- `history/memory`
+
+Each bundle exports a `createHistory` method you can use to create your own history object. In addition, `history/browser` and `history/hash` export a singleton instance you can use which reflects the state of [the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document).
 
 ## Basic Usage
 
 Basic usage looks like this:
 
 ```js
-import { createBrowserHistory } from 'history';
-
-const history = createBrowserHistory();
+// Import the browser history singleton instance.
+import history from 'history/browser';
+// Alternatively, if you're using hash history import
+// the hash history singleton instance.
+// import history from 'history/hash';
 
 // Get the current location.
-const location = history.location;
+let location = history.location;
 
 // Listen for changes to the current location.
-const unlisten = history.listen((location, action) => {
-  // location is an object like window.location
+let unlisten = history.listen(({ location, action }) => {
   console.log(action, location.pathname, location.state);
 });
 
-// Use push, replace, and go to navigate around.
+// Use push to push a new entry onto the history stack.
 history.push('/home', { some: 'state' });
 
+// Use replace to replace the current entry in the stack.
+history.replace('/logged-in');
+
+// Use back/forward to navigate one entry back or forward.
+history.back();
+
 // To stop listening, call the function returned from listen().
 unlisten();
 ```
 
-The options that each `create` method takes, along with its default values, are:
+If you're using `history/memory` you'll need to create your own `history` object before you can use it.
 
 ```js
-createBrowserHistory({
-  basename: '', // The base URL of the app (see below)
-  forceRefresh: false, // Set true to force full page refreshes
-  keyLength: 6, // The length of location.key
-  // A function to use to confirm navigation with the user (see below)
-  getUserConfirmation: (message, callback) => callback(window.confirm(message))
-});
+import { createHistory } from 'history/memory';
+let history = createHistory();
+```
 
-createHashHistory({
-  basename: '', // The base URL of the app (see below)
-  hashType: 'slash', // The hash type to use (see below)
-  // A function to use to confirm navigation with the user (see below)
-  getUserConfirmation: (message, callback) => callback(window.confirm(message))
-});
+If you're using browser or hash history with a `window` other than that of the current `document` (like an iframe), you'll need to create your own browser/hash history:
 
-createMemoryHistory({
-  initialEntries: ['/'], // The initial URLs in the history stack
-  initialIndex: 0, // The starting index in the history stack
-  keyLength: 6, // The length of location.key
-  // A function to use to confirm navigation with the user. Required
-  // if you return string prompts from transition hooks (see below)
-  getUserConfirmation: null
+```js
+import { createHistory } from 'history/browser';
+let history = createHistory({
+  window: iframe.contentWindow
 });
 ```
 
 ## Properties
 
 Each `history` object has the following properties:
 
-- `history.length` - The number of entries in the history stack
 - `history.location` - The current location (see below)
 - `history.action` - The current navigation action (see below)
 
-Additionally, `createMemoryHistory` provides `history.index` and `history.entries` properties that let you inspect the history stack.
+Additionally, memory history provides `history.index` that tells you the current index in the history stack.
 
 ## Listening
 
 You can listen for changes to the current location using `history.listen`:
 
 ```js
-history.listen((location, action) => {
+history.listen(({ action, location }) => {
   console.log(
     `The current URL is ${location.pathname}${location.search}${location.hash}`
   );
@@ -94,17 +94,22 @@ The `location` object implements a subset of [the `window.location` interface](h
 
 Locations may also have the following properties:
 
-- `location.state` - Some extra state for this location that does not reside in the URL (supported in `createBrowserHistory` and `createMemoryHistory`)
-- `location.key` - A unique string representing this location (supported in `createBrowserHistory` and `createMemoryHistory`)
+- `location.state` - Some extra state for this location that does not reside in the URL
+- `location.key` - A unique string representing this location
 
 The `action` is one of `PUSH`, `REPLACE`, or `POP` depending on how the user got to the current URL.
 
+- A `PUSH` means one more entry was added to the history stack
+- A `REPLACE` means the current entry in the stack was replaced
+- A `POP` means we went to some other location already in the stack
+
 ## Cleaning up
 
 When you attach a listener using `history.listen`, it returns a function that can be used to remove the listener, which can then be invoked in cleanup logic:
 
 ```js
-const unlisten = history.listen(myListener);
-// ...
+let unlisten = history.listen(myListener);
+
+// Later, when you're done...
 unlisten();
 ```