From 0f95d29539cc6c7b30d4540852d3821ccaf09bd5 Mon Sep 17 00:00:00 2001 From: Michael Jackson Date: Mon, 8 Jun 2020 12:10:13 -0700 Subject: [PATCH] More tweaks to API docs --- docs/api-reference.md | 125 +++++++++++++++++++++++----------------- docs/getting-started.md | 73 ++++++++++------------- 2 files changed, 100 insertions(+), 98 deletions(-) diff --git a/docs/api-reference.md b/docs/api-reference.md index 3e3141599..d406212c9 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -1,41 +1,32 @@ - + # 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 - - - -## `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. + + + +## 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) + + + +### 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'; @@ -44,11 +35,17 @@ let history = createBrowserHistory(); See [the Getting Started guide](getting-started.md) for more information. - + + +### 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'; @@ -57,11 +54,22 @@ let history = createHashHistory(); See [the Getting Started guide](getting-started.md) for more information. - + -## `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'; @@ -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`. -
-type InitialEntry = Path | LocationPieces;
-
- See [the Getting Started guide](getting-started.md) for more information. @@ -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: -- `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. -- `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. -- `Action.Replace` - Indicates the entry at the - current index in the history stack being replaced by a new one. +- `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. +- `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. +- `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. @@ -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. + + + +## 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; +} +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index dc244c262..d4512873d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,37 +1,21 @@ + + + # 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 @@ -89,6 +73,8 @@ let history = createBrowserHistory({ }); ``` + + ## Properties Each `history` object has the following properties: @@ -96,8 +82,9 @@ 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. + + ## Listening @@ -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 @@ -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 + + ## 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); @@ -143,10 +127,11 @@ let unlisten = history.listen(myListener); unlisten(); ``` + + ## 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');