Hickory

A single page application navigation system that works in the browser or in memory.

Documentation

You can learn about Hickory and read up on the APIs in the documentation

Inspiration

Hickory is heavily inspired by the history package and the history modules from vue-router.

Packages

This repository is a monorepo for the Hickory packages. Unless you are creating your own customized history type, you only need to know about three of them:

Package	Version	Repo	API
browser		packages/browser	API
hash		packages/hash	API
in-memory		packages/in-memory	API

Usage

Below is a quick introduction to the API of a history object.

import { Browser } from "@hickory/browser";

let history = Browser();

// You must add a respond handler function. Whenever there
// is navigation, that function will be called. It is responsible
// for finishing the navigation. "finish" should not be called until
// after any route matching/data loaded has finished running.
history.respondWith(({ location, action, finish, cancel }) => {
  console.log("Navigating to:", location);
  finish();
});

// All of the locations that are visited by the user of your
// application will be stored in an array. An index value is used to keep
// track of which location in the array is the current one.

// There are two navigation methods that you can use to change locations.

// navigate() is used for navigating to a new location.
// It has three modes: "anchor", "push", and "replace".
// "push" pushes the new location onto the session history after the current location
// "replace" replaces the current location in the session history
// "anchor" (default) acts like "push" for new locations and "replace" when the provided location
//   is the same as the current location (the same behavior as clicking an <a>).
// The first argument to navigate() is either a string or a partial location object.
// The optional second argument is the navigation mode ("anchor" if not provided).

// mode = "anchor"
history.navigate("/next-location");
// mode = "push"
history.navigate("/new-location", "push");
// mode = "replace"
history.navigate("/same-location", "replace");

// go() is used to jump to existing locations in the session history.
// negative values go backwards and positive values go forwards

// current index = 4
history.go(-2);
// new index = 2

// You might want to have you users confirm navigation before actually
// switching pages. To do this, pass a confirmation function to the
// confirm method.

history.confirm(function(info, allow, prevent) {
  let confirmed = window.confirm("Are you sure you want to navigate?");
  if (confirmed) {
    allow();
  } else {
    prevent();
  }
});

// Now, whenever there is navigation (the user clicks a link or the browser's
// forward/back buttons), the confirmation function will be run and the
// navigation will be cancelled if the prevent function is called.

// In the above example, if the user clicks the cancel button of the
// "confirm" popup, then the navigation will be cancelled. If the user clicks
// the "OK" button, then the navigation will occur.

// If/when you no longer want the user to have to confirm navigation, call
// the confirm function with no argument and navigation will always happen.

history.confirm();

Browser Support

Browser testing is provided thanks to BrowserStack

The following browsers are currently tested:

• Chrome 63 on Windows 10
• Firefox 57 on Windows 10
• Internet Explorer 11 on Windows 10
• Edge 16 on Windows 10
• Safari 12 on macOS Mojave