Skip to content

Commit

Permalink
More tweaks to API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mjackson
mjackson committed Jun 8, 2020
1 parent f88b174 commit 0f95d29
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 98 deletions.
125 changes: 71 additions & 54 deletions docs/api-reference.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,32 @@
<a name="history-api-reference"></a>
<a name="top"></a>

# history API Reference

This is the API reference for [the history JavaScript library](https://github.com/ReactTraining/history). The source code is TypeScript, but it is compiled to JavaScript before publishing. The function signatures in this reference all include their TypeScript type annotations for conciseness and clarity.

Although there are several APIs in the history library, the main interfaces are:

- The create\* methods:
- [`createBrowserHistory({ window?: Window })`](#createbrowserhistory)
- [`createHashHistory({ window?: Window })`](#createhashhistory)
- [`createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number })`](#creatememoryhistory)
- The [`History`](#history) interface
- [`history.action`](#history.action)
- [`history.location`](#history.location)
- [`history.createHref(to: To)`](#history.createhref)
- [`history.push(to: To, state?: State)`](#history.push)
- [`history.replace(to: To, state?: State)`](#history.replace)
- [`history.go(delta: number)`](#history.go)
- [`history.back()`](#history.back)
- [`history.forward()`](#history.forward)
- [`history.listen(listener: Listener)`](#history.listen)
- [`history.block(blocker: Blocker)`](#history.block)
- The [`Location`](#location) interface
- [`location.pathname`](#location.pathname)
- [`location.search`](#location.search)
- [`location.hash`](#location.hash)
- [`location.state`](#location.state)
- [`location.key`](#location.key)
- The [`Action`](#action) enum
- The [`To`](#to) type alias
- The [`State`](#state) type alias

<a name="createbrowserhistory"></a>

## `createBrowserHistory({ window?: Window })`

Returns a [`BrowserHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L306) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
This is the API reference for [the history JavaScript library](https://github.com/ReactTraining/history).

The [source code](https://github.com/ReactTraining/history/tree/dev/packages/history) for this library is written in TypeScript, but it is compiled to JavaScript before publishing. Some of the function signatures in this reference include their TypeScript type annotations, but you can always refer to the original source as well.

<a name="overview"></a>

## Overview

This library includes three `history` object initializers for the different modes we support. They are:

- [Browser history](#browserhistory)
- [Hash history](#hashhistory)
- [Memory history](#memoryhistory)

<a name="browserhistory"></a>

### Browser History

A "browser history" object is designed to be run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event.

```ts
declare createBrowserHistory({ window?: Window }): BrowserHistory;
```

`createBrowserHistory` returns a [`BrowserHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L306) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).

```ts
import { createBrowserHistory } from 'history';
Expand All @@ -44,11 +35,17 @@ let history = createBrowserHistory();

See [the Getting Started guide](getting-started.md) for more information.

<a name="createhashhistory"></a>
<a name="hashhistory"></a>

### Hash History

## `createHashHistory({ window?: Window })`
A "hash history" object is designed to be run in modern web browsers that support the HTML5 history interface including `pushState`, `replaceState`, and the `popstate` event. The main difference between this and [browser history](#createbrowserhistory) is that a hash history stores the current location in the `hash` portion of the URL, which means that it is not ever sent to the server.

Returns a [`HashHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L317) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).
```ts
declare createHashHistory({ window?: Window }): HashHistory;
```

`createHashHistory` returns a [`HashHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L317) instance for the given `window`, which defaults to [the `defaultView` of the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/defaultView).

```ts
import { createHashHistory } from 'history';
Expand All @@ -57,11 +54,22 @@ let history = createHashHistory();

See [the Getting Started guide](getting-started.md) for more information.

<a name="creatememoryhistory"></a>
<a name="memoryhistory"></a>

## `createMemoryHistory({ initialEntries?: InitialEntry[], initialIndex?: number })`
### Memory History

Returns a [`MemoryHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L324) instance.
A "memory history" object stores all locations internally in an array. This makes it ideal as a reference implementation and for situations where you need complete control over the history stack, like tests and React Native.

```ts
declare createMemoryHistory({
initialEntries?: InitialEntry[],
initialIndex?: number
}): MemoryHistory;

type InitialEntry = Path | LocationPieces;
```

`createMemoryHistory` returns a [`MemoryHistory`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L324) instance.

```ts
import { createMemoryHistory } from 'history';
Expand All @@ -70,10 +78,6 @@ let history = createMemoryHistory();

You can provide initial entries to this history instance through the `initialEntries` property, which defaults to `['/']` (a single location at the root `/` URL). The `initialIndex` defaults to the index of the last item in `initialEntries`.

<pre>
type InitialEntry = <a href="https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L32">Path</a> | <a href="https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L100">LocationPieces</a>;
</pre>

See [the Getting Started guide](getting-started.md) for more information.

<a name="history"></a>
Expand Down Expand Up @@ -258,15 +262,9 @@ This can be useful in situations where you need to keep track of 2 different sta

An [`Action`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L4) represents a type of change that occurred in the history stack. `Action` is an `enum` with three members:

- <a name="action.pop"></a> `Action.Pop` - A change to an arbitrary index in the
stack, such as a back or forward navigation. This does not describe the
direction of the navigation, only that the index changed. This is the default
action for newly created history objects.
- <a name="action.push"></a> `Action.Push` - Indicates a new entry being added
to the history stack, such as when a link is clicked and a new page loads.
When this happens, all subsequent entries in the stack are lost.
- <a name="action.replace"></a> `Action.Replace` - Indicates the entry at the
current index in the history stack being replaced by a new one.
- <a name="action.pop"></a> `Action.Pop` - A change to an arbitrary index in the stack, such as a back or forward navigation. This does not describe the direction of the navigation, only that the index changed. This is the default action for newly created history objects.
- <a name="action.push"></a> `Action.Push` - Indicates a new entry being added to the history stack, such as when a link is clicked and a new page loads. When this happens, all subsequent entries in the stack are lost.
- <a name="action.replace"></a> `Action.Replace` - Indicates the entry at the current index in the history stack being replaced by a new one.

See [the Getting Started guide](getting-started.md) for more information.

Expand All @@ -285,3 +283,22 @@ See [the Navigation guide](navigation.md) for more information.
A [`State`](https://github.com/ReactTraining/history/blob/0f992736/packages/history/index.ts#L61) value is an object of extra information that is associated with a [`Location`](#location) but that does not appear in the URL. This value is always associated with that location.

See [the Navigation guide](navigation.md) for more information.

<a name="creating-and-parsing-paths"></a>

## Creating and Parsing Paths

The library also exports `createPath` and `parsePath` methods that are useful when working with URL paths.

```ts
declare createPath(pieces: PathPieces): Path;
declare parsePath(path: Path): PathPieces;

type Path = string;

interface PathPieces {
pathname?: string;
search?: string;
hash?: string;
}
```
73 changes: 29 additions & 44 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,21 @@
<a name="top"></a>
<a name="intro"></a>

# Intro

The history library provides history tracking and navigation primitives for
JavaScript applications that run in browsers and other stateful environments.

If you haven't yet, please take a second to read through [the Installation
guide](installation.md) to get the library installed and running on your system.

We provide 3 different methods for working with history, depending on your
environment:

- 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

The main bundle exports one method for each environment:
[`createBrowserHistory`](api-reference.md#createbrowserhistory) for browsers,
[`createHashHistory`](api-reference.md#createhashhistory) for using hash history
in browsers, and [`createMemoryHistory`](api-reference.md#creatememoryhistory)
for creating an in-memory history.

In addition to the main bundle, the library also includes `history/browser` and
`history/hash` bundles that export singletons you can use to quickly get a
history instance for [the current
`document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document)
(web page).
The history library provides history tracking and navigation primitives for JavaScript applications that run in browsers and other stateful environments.

If you haven't yet, please take a second to read through [the Installation guide](installation.md) to get the library installed and running on your system.

We provide 3 different methods for working with history, depending on your environment:

- 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

The main bundle exports one method for each environment: [`createBrowserHistory`](api-reference.md#createbrowserhistory) for browsers, [`createHashHistory`](api-reference.md#createhashhistory) for using hash history in browsers, and [`createMemoryHistory`](api-reference.md#creatememoryhistory) for creating an in-memory history.

In addition to the main bundle, the library also includes `history/browser` and `history/hash` bundles that export singletons you can use to quickly get a history instance for [the current `document`](https://developer.mozilla.org/en-US/docs/Web/API/Window/document) (web page).

## Basic Usage

Expand Down Expand Up @@ -89,15 +73,18 @@ let history = createBrowserHistory({
});
```

<a name="properties"></a>

## Properties

Each `history` object has the following properties:

- [`history.location`](api-reference.md#history.location) - The current location (see below)
- [`history.action`](api-reference.md#history.action) - The current navigation action (see below)

Additionally, memory history provides `history.index` that tells you the current
index in the history stack.
Additionally, memory history provides `history.index` that tells you the current index in the history stack.

<a name="listening"></a>

## Listening

Expand All @@ -112,10 +99,7 @@ history.listen(({ action, location }) => {
});
```

The [`location`](api-reference.md#location) object implements a subset of [the
`window.location`
interface](https://developer.mozilla.org/en-US/docs/Web/API/Location),
including:
The [`location`](api-reference.md#location) object implements a subset of [the `window.location` interface](https://developer.mozilla.org/en-US/docs/Web/API/Location), including:

- [`location.pathname`](api-reference.md#location.pathname) - The path of the URL
- [`location.search`](api-reference.md#location.search) - The URL query string
Expand All @@ -124,17 +108,17 @@ including:
location that does not reside in the URL (may be `null`)
- [`location.key`](api-reference.md#location.key) - A unique string representing this location

The [`action`](api-reference.md#action) is one of `Action.Push`, `Action.Replace`,
or `Action.Pop` depending on how the user got to the current location.
The [`action`](api-reference.md#action) is one of `Action.Push`, `Action.Replace`, or `Action.Pop` depending on how the user got to the current location.

- `Action.Push` means one more entry was added to the history stack
- `Action.Replace` means the current entry in the stack was replaced
- `Action.Pop` means we went to some other location already in the stack

<a name="cleaning-up"></a>

## 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:
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
let unlisten = history.listen(myListener);
Expand All @@ -143,10 +127,11 @@ let unlisten = history.listen(myListener);
unlisten();
```

<a name="utilities"></a>

## Utilities

The main history bundle also contains both `createPath` and `parsePath` methods
that may be useful when working with URL paths.
The main history bundle also contains both `createPath` and `parsePath` methods that may be useful when working with URL paths.

```js
let pathPieces = parsePath('/the/path?the=query#the-hash');
Expand Down

0 comments on commit 0f95d29

Please sign in to comment.