1 | /**
|
2 | * Actions represent the type of change to a location value.
|
3 | *
|
4 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#action
|
5 | */
|
6 | export declare enum Action {
|
7 | /**
|
8 | * A POP indicates a change to an arbitrary index in the history stack, such
|
9 | * as a back or forward navigation. It does not describe the direction of the
|
10 | * navigation, only that the current index changed.
|
11 | *
|
12 | * Note: This is the default action for newly created history objects.
|
13 | */
|
14 | Pop = "POP",
|
15 | /**
|
16 | * A PUSH indicates a new entry being added to the history stack, such as when
|
17 | * a link is clicked and a new page loads. When this happens, all subsequent
|
18 | * entries in the stack are lost.
|
19 | */
|
20 | Push = "PUSH",
|
21 | /**
|
22 | * A REPLACE indicates the entry at the current index in the history stack
|
23 | * being replaced by a new one.
|
24 | */
|
25 | Replace = "REPLACE"
|
26 | }
|
27 | /**
|
28 | * A URL pathname, beginning with a /.
|
29 | *
|
30 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.pathname
|
31 | */
|
32 | export declare type Pathname = string;
|
33 | /**
|
34 | * A URL search string, beginning with a ?.
|
35 | *
|
36 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.search
|
37 | */
|
38 | export declare type Search = string;
|
39 | /**
|
40 | * A URL fragment identifier, beginning with a #.
|
41 | *
|
42 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.hash
|
43 | */
|
44 | export declare type Hash = string;
|
45 | /**
|
46 | * An object that is used to associate some arbitrary data with a location, but
|
47 | * that does not appear in the URL path.
|
48 | *
|
49 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.state
|
50 | */
|
51 | export declare type State = object | null;
|
52 | /**
|
53 | * A unique string associated with a location. May be used to safely store
|
54 | * and retrieve data in some other storage API, like `localStorage`.
|
55 | *
|
56 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.key
|
57 | */
|
58 | export declare type Key = string;
|
59 | /**
|
60 | * The pathname, search, and hash values of a URL.
|
61 | */
|
62 | export interface Path {
|
63 | /**
|
64 | * A URL pathname, beginning with a /.
|
65 | *
|
66 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.pathname
|
67 | */
|
68 | pathname: Pathname;
|
69 | /**
|
70 | * A URL search string, beginning with a ?.
|
71 | *
|
72 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.search
|
73 | */
|
74 | search: Search;
|
75 | /**
|
76 | * A URL fragment identifier, beginning with a #.
|
77 | *
|
78 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.hash
|
79 | */
|
80 | hash: Hash;
|
81 | }
|
82 | /**
|
83 | * An entry in a history stack. A location contains information about the
|
84 | * URL path, as well as possibly some arbitrary state and a key.
|
85 | *
|
86 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location
|
87 | */
|
88 | export interface Location<S extends State = State> extends Path {
|
89 | /**
|
90 | * An object of arbitrary data associated with this location.
|
91 | *
|
92 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.state
|
93 | */
|
94 | state: S;
|
95 | /**
|
96 | * A unique string associated with this location. May be used to safely store
|
97 | * and retrieve data in some other storage API, like `localStorage`.
|
98 | *
|
99 | * Note: This value is always "default" on the initial location.
|
100 | *
|
101 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.key
|
102 | */
|
103 | key: Key;
|
104 | }
|
105 | /**
|
106 | * A partial Path object that may be missing some properties.
|
107 | */
|
108 | export interface PartialPath {
|
109 | /**
|
110 | * The URL pathname, beginning with a /.
|
111 | *
|
112 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.pathname
|
113 | */
|
114 | pathname?: Pathname;
|
115 | /**
|
116 | * The URL search string, beginning with a ?.
|
117 | *
|
118 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.search
|
119 | */
|
120 | search?: Search;
|
121 | /**
|
122 | * The URL fragment identifier, beginning with a #.
|
123 | *
|
124 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.hash
|
125 | */
|
126 | hash?: Hash;
|
127 | }
|
128 | /**
|
129 | * A partial Location object that may be missing some properties.
|
130 | */
|
131 | export interface PartialLocation<S extends State = State> extends PartialPath {
|
132 | /**
|
133 | * An object of arbitrary data associated with this location.
|
134 | *
|
135 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.state
|
136 | */
|
137 | state?: S;
|
138 | /**
|
139 | * A unique string associated with this location. May be used to safely store
|
140 | * and retrieve data in some other storage API, like `localStorage`.
|
141 | *
|
142 | * Note: This value is always "default" on the initial location.
|
143 | *
|
144 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#location.key
|
145 | */
|
146 | key?: Key;
|
147 | }
|
148 | /**
|
149 | * A change to the current location.
|
150 | */
|
151 | export interface Update<S extends State = State> {
|
152 | /**
|
153 | * The action that triggered the change.
|
154 | */
|
155 | action: Action;
|
156 | /**
|
157 | * The new location.
|
158 | */
|
159 | location: Location<S>;
|
160 | }
|
161 | /**
|
162 | * A function that receives notifications about location changes.
|
163 | */
|
164 | export interface Listener<S extends State = State> {
|
165 | (update: Update<S>): void;
|
166 | }
|
167 | /**
|
168 | * A change to the current location that was blocked. May be retried
|
169 | * after obtaining user confirmation.
|
170 | */
|
171 | export interface Transition<S extends State = State> extends Update<S> {
|
172 | /**
|
173 | * Retries the update to the current location.
|
174 | */
|
175 | retry(): void;
|
176 | }
|
177 | /**
|
178 | * A function that receives transitions when navigation is blocked.
|
179 | */
|
180 | export interface Blocker<S extends State = State> {
|
181 | (tx: Transition<S>): void;
|
182 | }
|
183 | /**
|
184 | * Describes a location that is the destination of some navigation, either via
|
185 | * `history.push` or `history.replace`. May be either a URL or the pieces of a
|
186 | * URL path.
|
187 | */
|
188 | export declare type To = string | PartialPath;
|
189 | /**
|
190 | * A history is an interface to the navigation stack. The history serves as the
|
191 | * source of truth for the current location, as well as provides a set of
|
192 | * methods that may be used to change it.
|
193 | *
|
194 | * It is similar to the DOM's `window.history` object, but with a smaller, more
|
195 | * focused API.
|
196 | */
|
197 | export interface History<S extends State = State> {
|
198 | /**
|
199 | * The last action that modified the current location. This will always be
|
200 | * Action.Pop when a history instance is first created. This value is mutable.
|
201 | *
|
202 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.action
|
203 | */
|
204 | readonly action: Action;
|
205 | /**
|
206 | * The current location. This value is mutable.
|
207 | *
|
208 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.location
|
209 | */
|
210 | readonly location: Location<S>;
|
211 | /**
|
212 | * Returns a valid href for the given `to` value that may be used as
|
213 | * the value of an <a href> attribute.
|
214 | *
|
215 | * @param to - The destination URL
|
216 | *
|
217 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.createHref
|
218 | */
|
219 | createHref(to: To): string;
|
220 | /**
|
221 | * Pushes a new location onto the history stack, increasing its length by one.
|
222 | * If there were any entries in the stack after the current one, they are
|
223 | * lost.
|
224 | *
|
225 | * @param to - The new URL
|
226 | * @param state - Data to associate with the new location
|
227 | *
|
228 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.push
|
229 | */
|
230 | push(to: To, state?: S): void;
|
231 | /**
|
232 | * Replaces the current location in the history stack with a new one. The
|
233 | * location that was replaced will no longer be available.
|
234 | *
|
235 | * @param to - The new URL
|
236 | * @param state - Data to associate with the new location
|
237 | *
|
238 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.replace
|
239 | */
|
240 | replace(to: To, state?: S): void;
|
241 | /**
|
242 | * Navigates `n` entries backward/forward in the history stack relative to the
|
243 | * current index. For example, a "back" navigation would use go(-1).
|
244 | *
|
245 | * @param delta - The delta in the stack index
|
246 | *
|
247 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.go
|
248 | */
|
249 | go(delta: number): void;
|
250 | /**
|
251 | * Navigates to the previous entry in the stack. Identical to go(-1).
|
252 | *
|
253 | * Warning: if the current location is the first location in the stack, this
|
254 | * will unload the current document.
|
255 | *
|
256 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.back
|
257 | */
|
258 | back(): void;
|
259 | /**
|
260 | * Navigates to the next entry in the stack. Identical to go(1).
|
261 | *
|
262 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.forward
|
263 | */
|
264 | forward(): void;
|
265 | /**
|
266 | * Sets up a listener that will be called whenever the current location
|
267 | * changes.
|
268 | *
|
269 | * @param listener - A function that will be called when the location changes
|
270 | * @returns unlisten - A function that may be used to stop listening
|
271 | *
|
272 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.listen
|
273 | */
|
274 | listen(listener: Listener<S>): () => void;
|
275 | /**
|
276 | * Prevents the current location from changing and sets up a listener that
|
277 | * will be called instead.
|
278 | *
|
279 | * @param blocker - A function that will be called when a transition is blocked
|
280 | * @returns unblock - A function that may be used to stop blocking
|
281 | *
|
282 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#history.block
|
283 | */
|
284 | block(blocker: Blocker<S>): () => void;
|
285 | }
|
286 | /**
|
287 | * A browser history stores the current location in regular URLs in a web
|
288 | * browser environment. This is the standard for most web apps and provides the
|
289 | * cleanest URLs the browser's address bar.
|
290 | *
|
291 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#browserhistory
|
292 | */
|
293 | export interface BrowserHistory<S extends State = State> extends History<S> {
|
294 | }
|
295 | /**
|
296 | * A hash history stores the current location in the fragment identifier portion
|
297 | * of the URL in a web browser environment.
|
298 | *
|
299 | * This is ideal for apps that do not control the server for some reason
|
300 | * (because the fragment identifier is never sent to the server), including some
|
301 | * shared hosting environments that do not provide fine-grained controls over
|
302 | * which pages are served at which URLs.
|
303 | *
|
304 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#hashhistory
|
305 | */
|
306 | export interface HashHistory<S extends State = State> extends History<S> {
|
307 | }
|
308 | /**
|
309 | * A memory history stores locations in memory. This is useful in stateful
|
310 | * environments where there is no web browser, such as node tests or React
|
311 | * Native.
|
312 | *
|
313 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#memoryhistory
|
314 | */
|
315 | export interface MemoryHistory<S extends State = State> extends History<S> {
|
316 | index: number;
|
317 | }
|
318 | export declare type BrowserHistoryOptions = {
|
319 | window?: Window;
|
320 | };
|
321 | /**
|
322 | * Browser history stores the location in regular URLs. This is the standard for
|
323 | * most web apps, but it requires some configuration on the server to ensure you
|
324 | * serve the same app at multiple URLs.
|
325 | *
|
326 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#createbrowserhistory
|
327 | */
|
328 | export declare function createBrowserHistory(options?: BrowserHistoryOptions): BrowserHistory;
|
329 | export declare type HashHistoryOptions = {
|
330 | window?: Window;
|
331 | };
|
332 | /**
|
333 | * Hash history stores the location in window.location.hash. This makes it ideal
|
334 | * for situations where you don't want to send the location to the server for
|
335 | * some reason, either because you do cannot configure it or the URL space is
|
336 | * reserved for something else.
|
337 | *
|
338 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#createhashhistory
|
339 | */
|
340 | export declare function createHashHistory(options?: HashHistoryOptions): HashHistory;
|
341 | /**
|
342 | * A user-supplied object that describes a location. Used when providing
|
343 | * entries to `createMemoryHistory` via its `initialEntries` option.
|
344 | */
|
345 | export declare type InitialEntry = string | PartialLocation;
|
346 | export declare type MemoryHistoryOptions = {
|
347 | initialEntries?: InitialEntry[];
|
348 | initialIndex?: number;
|
349 | };
|
350 | /**
|
351 | * Memory history stores the current location in memory. It is designed for use
|
352 | * in stateful non-browser environments like tests and React Native.
|
353 | *
|
354 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#creatememoryhistory
|
355 | */
|
356 | export declare function createMemoryHistory(options?: MemoryHistoryOptions): MemoryHistory;
|
357 | /**
|
358 | * Creates a string URL path from the given pathname, search, and hash components.
|
359 | *
|
360 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#createpath
|
361 | */
|
362 | export declare function createPath({ pathname, search, hash }: PartialPath): string;
|
363 | /**
|
364 | * Parses a string URL path into its separate pathname, search, and hash components.
|
365 | *
|
366 | * @see https://github.com/ReactTraining/history/tree/master/docs/api-reference.md#parsepath
|
367 | */
|
368 | export declare function parsePath(path: string): PartialPath;
|