oaf-project / oaf-navi

An accessible wrapper for Navi.

Oaf Navi

An accessible wrapper for Navi.

Documentation at https://oaf-project.github.io/oaf-navi/

Features

• Reset scroll and focus after PUSH and REPLACE navigation
• Restore scroll and focus after POP navigation
• Set the page title after navigation
• Announce navigation to users of screen readers
• Hash fragment support

In lieu of more details, see Oaf React Router for now. The features are basically the same.

Installation

# yarn
yarn add oaf-navi

# npm
npm install oaf-navi

Basic Usage

import register from "navi-scripts/register";
import routes from "./routes";
import { createBrowserNavigation } from "navi";
+ import { createBrowserHistory } from "history";
+ import { wrapNavigation } from "oaf-navi";

register({
  ...
  async main() {
-    const navigation = createBrowserNavigation({ routes });
+    const history = createBrowserHistory(); // or createHashHistory()
+    const navigation = createBrowserNavigation({ routes, history });
+    await wrapNavigation(history, navigation);
    ...
  }
});

Advanced Usage

const settings = {
  announcementsDivId: "announcements",
  primaryFocusTarget: "main h1, [role=main] h1",
  // This assumes you're setting the document title via some other means (e.g. React Helmet).
  // If you're not, you should return a unique and descriptive page title for each page
  // from this function and set `setPageTitle` to true.
  documentTitle: (route: Route) => new Promise(resolve => setTimeout(() => resolve(document.title))),
  // BYO localization
  navigationMessage: (title: string, route: Route, action: Action): string => `Navigated to ${title}.`,
  shouldHandleAction: (previousRoute: Route, nextRoute: Route, action: Action) => true,
  disableAutoScrollRestoration: true,
  announcePageNavigation: true,
  setPageTitle: false,
  handleHashFragment: true,
  // Set this to false if you are using createHashHistory or createMemoryHistory.
  restorePageStateOnPop: true,
  // Set this to true for smooth scrolling.
  // For browser compatibility you might want iamdustan's smoothscroll polyfill https://github.com/iamdustan/smoothscroll
  smoothScroll: false,
};

const history = createBrowserHistory();
const navigation = createBrowserNavigation({ routes, history });
await wrapNavigation(history, navigation);
...

A note on focus outlines

You may see focus outlines around your h1 elements (or elsewhere, per primaryFocusTarget) when using Oaf Navi.

You might be tempted to remove these focus outlines with something like the following:

[tabindex="-1"]:focus {
  outline: 0 !important;
}

Don't do this! Focus outlines are important for accessibility. See for example:

• https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-visible.html
• https://www.w3.org/TR/2016/NOTE-WCAG20-TECHS-20161007/F78
• http://www.outlinenone.com/

Note that Bootstrap 4 unfortunately removes these focus outlines. If you use Bootstrap, you can restore them with Oaf Bootstrap 4.

All that said, if you absolutely must remove focus outlines (stubborn client, stubborn boss, stubborn designer, whatever), consider using the :focus-visible polyfill so focus outlines are only hidden from mouse users, not keyboard users.

See also

• Oaf Routing
• Oaf Side Effects
• React-axe

oaf-navi's Issues

Migrate away from history.block

An in-range update of oaf-routing is breaking the build 🚨

The dependency oaf-routing was updated from 3.0.0 to 3.0.1.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

oaf-routing is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Port from tslint to eslint

Don't announce hash fragment-only URL changes

Reset focus when routing fails?

Grab the title straight from the route instead of from document.title

Do we need to handle first page load?

Navi sets the page title for us, so that just leaves scrolling to (and focusing!) the element identified by the hash fragment. Does Navi take care of this too (both scrolling AND focusing)?

100% test coverage

An in-range update of oaf-routing is breaking the build 🚨

The dependency oaf-routing was updated from 0.6.0 to 0.6.1.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

oaf-routing is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build failed (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

An in-range update of type-coverage is breaking the build 🚨

The devDependency type-coverage was updated from 2.0.4 to 2.1.0.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

type-coverage is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).

---

Commits

The new version differs by 15 commits.

• 51790ee v2.1.0
• 92dbffc chore: use yarn workspaces
• 0576777 fix: ci failure
• ba61be7 feat: extract ts-lib-utils package
• 94385d4 fix: lint error
• 864a21c chore: update dependencies
• f124bef fix: ci failure
• 53db314 refactor: remove standard
• 815132a feat: add eslint rules
• 5ad7db0 refactor: use eslint instead of tslint
• d8e79bf chore: update dependencies
• 4bd0f8d docs: add info about type-coverage-watcher to the readme
• b227529 chore: update no-unused-export
• 00e6c14 chore: update no-unused-export
• fbab1cf chore: update no-unused-export

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

An in-range update of @types/history is breaking the build 🚨

The devDependency @types/history was updated from 4.7.2 to 4.7.3.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

@types/history is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴