<commit_before># Introduction

Welcome use this driver!  
It help you manage browser history and receive `Location`.  

# Concepts

`Location` represents a url with related state.

```ts
interface Location {
  host: string,
  protocol: string,
  path: string,
  canonicalPath: string, // path without baseName
  baseName?: string,
  state?: any,
  queryString?: {
    [name: string]: string
  }
}
```

`Action` represents a history operation:  

- push : Adds new `Location` into history stack.
- replace : Updates the most recent entry on the history stack to newly `Location`.
- forward : Goes to the next page in history stack.
- back : Goes to the previous page.

```ts
enum Action {
  push,
  replace,
  forward,
  back
}
```

User uses `Directive` to controls history behavior.  
location is optional,  
because not all action needs it.  
such as `back` action.

```ts
interface Directive {
  location?: Location,
  action: Action
}
```

Driver sends a `Context` to your data component when history changed.  

```ts
interface Context {
  name?: string,
  location: Location,
  args?: {
    [name: string]: string
  }
}
```

Finally, driver accepts an optional `Option` to initialization.

```ts
interface Option {
  hash?: boolean,
  baseName?: string,
  click?: boolean,
  patterns?: {
    [name: string]: string
  }
}
```

Detail of option:

- hash : Use hash fragment instead of url.
- baseName : If provided, all path will relatives to it.
- click : Whether to capture DOM click event.
- patterns : Define url pattern.

# Driver exports

```ts
function makePageDriver(option : Option) : (directive$ : Stream<Directive>) => Stream<Context>
```

Action is plain object.

```ts
const action = {
  push,
  replace,
  forward,
  back
}
```

# Work with path arguments.

please see [path-to-regexp#parameters](https://github.com/pillarjs/path-to-regexp#parameters) !

# Examples

Send initial `Directive`.

```ts
import {run} from "@cycle/xstream-run"
import {makePageDriver, action} from "cycle-page"<commit_msg>Update README.md document<commit_after># Introduction

This driver help you manage browser history and receive `Location`.  

# Concepts

`Location` represents a url with related state.

```ts
interface Location {
  host: string,
  protocol: string,
  path: string,
  canonicalPath: string, // path without baseName
  baseName?: string,
  state?: any,
  queryString?: {
    [name: string]: string
  }
}
```

`Action` represents a history operation:  

- push : Adds new `Location` into history stack.
- replace : Updates the most recent entry on the history stack to newly `Location`.
- forward : Goes to the next page in history stack.
- back : Goes to the previous page.

```ts
enum Action {
  push,
  replace,
  forward,
  back
}
```

User uses `Directive` to controls history behavior.  
location is optional,  
because not all action needs it.  
such as `back` action.

```ts
interface Directive {
  location?: Location,
  action: Action
}
```

Driver sends a `Context` to your data component when history changed.  

```ts
interface Context {
  name?: string,
  location: Location,
  args?: {
    [name: string]: string
  }
}
```

Finally, driver accepts an optional `Option` to initialization.

```ts
interface Option {
  hash?: boolean,
  baseName?: string,
  click?: boolean,
  patterns?: {
    [name: string]: string
  }
}
```

Detail of option:

- hash : Use hash fragment instead of url.
- baseName : If provided, all path will relatives to it.
- click : Whether to capture DOM click event.
- patterns : Define url pattern.

# Driver exports

Main function

```ts
function makePageDriver(option : Option) : (directive$ : Stream<Directive>) => Stream<Context>
```

and Action constant...

```ts
const action = {
  push,
  replace,
  forward,
  back
}
```

# Work with path arguments.

please see [path-to-regexp#parameters](https://github.com/pillarjs/path-to-regexp#parameters) !

# Examples

Send initial `Directive`.

```ts
import {run} from "@cycle/xstream-run"
import {makePageDriver, action} from "cycle-page"
{'fraction_non_alphanumeric': 0.1162215628090999, 'fraction_numerical': 0.0, 'mean_word_length': 3.708963911525029, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2665499', 'n_tokens_mistral': 1256, 'n_tokens_neox': 1218, 'n_words': 465}