# rhud

> Router

Latest version **1.0.0** (published 2020-03-28) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install rhud
pnpm add rhud
yarn add rhud
bun add rhud
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2020-03-28 |
| First published | 2020-03-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 39.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Sam Thorogood |
| Maintainers | samthor |

## Links

- npm: https://www.npmjs.com/package/rhud
- Repository: git@github.com:samthor/rhud
- npm.io page: https://npm.io/package/rhud

## Recent versions

- 1.0.0 (latest) — 2020-03-28

## README

Single-page-application router.
Installs a global listener for all clicks on `<a href="...">`.

# Install

Install via `rhud` using your favorite package manager.
Includes TS types.

# Usage

At its simplest, use like so:

```js
import {listen} from 'rhud';

listen(async (context) => {
  const partial = await loadPartialFor(context.href);
  context.ready(() => {
    updateDom(partial);
  });
});
```

This example will be called for every route (not those with "." in the URL, except ending with ".html").

## Options

You can configure not to be called immediately, and control which URLs are matched:

```js
listen((context) => {
  // ...
}, {
  firstRun: false,  // don't invoke immediately
  validate: (url) => url.pathname.exec(/^\/\w*$/),  // matches "/" or "/foo", not "/x/y" or "/foo/"
})
```

## Context

The listener you configure is passed an object of type `RouterContext`.
This contains the requested `href`, as well as:

* `isNavigation`: is this a navigation (e.g., click on link) or is it due to a back/forward history event
* `firstRun`: is this the first run (`isNavigation` will be false)
* `signal`: an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) that will be aborted if another route starts before this is complete
* `state`: the current or future `window.history.state`
* the `ready()` method: call when you're happy for the URL to change

### Navigation Mode

In navigation mode, say, the user clicking on a page link, the URL hasn't changed when the listener method is invoked.
Here's an example:

```js
listen(async (context) => {
  if (context.isNavigation) {
    // Here, the URL will still be the page's previous URL. Do long-lived tasks
    // like network fetches here.
  }

  // Call .ready() when you're happy for the URL to change.
  // The method you pass here should be synchronous (can be async if you must).
  context.ready(() => {
    // The URL has changed! Update your DOM synchronously! (This can be
    // important so relative images work correctly.)
    // Once this method returns, the page will scroll to any matched hash, e.g.
    // a link to "/foo#bar" will scroll to "#bar".
  });

  // If you have any more pending tasks here (e.g., loading JS for this page)
  // that can happen after the URL changes, block here.
});
```

If you're _not_ in navigation mode, this means the user has hit back or forward to change the URL.
In this case, the URL has already changed when the method opens.
You should aim to update the DOM _without_ doing any asynchronous calls, as the History API's default behavior is to scroll to the page after a frame.

```js
listen(async (context) => {
  if (context.isNavigation) {
    // ignore
  } else {
    // Get partial from cache if possible, but otherwise use network.
    // Avoid 'await'.
  }

  // as earlier
});
```

There are mitigation strategies if back/forward requires a network request to display properly.
You can save the scroll position when the listener runs, reset it after a frame, and then scroll to the intended position later.

## Requirements

Uses `Promise` (but not `async` or `await`), so probably works on modern browsers.
This includes a tiny `AbortSignal` and `AbortController` polyfill (as these are still fairly modern as of 2020).

---
_Source: https://npm.io/package/rhud · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._