npm package: @scb-dmc/reserve-nav
Description: Cross site navigation menu
Author: SCB DMC
Latest version: 1.3.5

# reserve-nav

reserve-nav is a project for a unified React based navigation menu.

## Node Versions

Ensure that Node version 16.0.0 or greater is installed and available.

## Getting Started

Create a file in the root of the project called `.env` with the following contents:

```
RESERVE_PRISMIC_URL=<prismic api url from reserve>
RESERVE_PRISMIC_TOKEN=<prismic token from reserve>
FETCH_MENU=true
LOCALE=en-us
RESERVE_TRACKING_ID=<tracking ID>
IMAGE_PREPROCESSOR=https://www.reservewheels.com/_next/image
```

Start the development server:

```
$ yarn start
```

The app will be running at [http://localhost:5000](http://localhost:5000).

### Menu Data

By default, the app will fetch new primary and footer menu data and write it to `./src/assets/primary-menu/<locale>.json` and `./src/assets/footer-menu/<locale>.json`, respectively.
when running the development server or building the web artifacts. This behavior can be overridden
by either changing `FETCH_MENU` in your environment file to `false`, or by overriding the
variable through the CLI. For example:

```sh
$ DOTENV_CONFIG_FETCH_MENU=false yarn build:web
```

#### Images

The menu is capable of displaying images in the NavCTABlock. The images
can be served through an optional preprocessor by supplying a URL to the `imagePreprocessor` prop
of `NavMenu`. This prop is required, but can be bypassed with an empty string (`""`). Currently,
this assumes a route to `/_next/image`.

##### Sizes

The Reserve Nav only handles images in the CTA block. There are no restrictions, it will just maintain it's aspect ratio.

### i18n

When running the dev server or building the web artifacts, localized menu data will be pulled
from Prismic for all locales and saved to `./src/assets/primary-menu/<locale>.json` and `./src/assets/footer-menu/<locale>.json`. By default, the
dev server will use `en-us` menu data, but this can be overridden by changing the path to the
menu JSON in `webpack.dev.config.js`.

#### reserve-wheels

i18n is not currently supported in reserve-wheels. When it is, simply pass the localized menu data to
the `NavMenu` component like any other translated object.

### Google Analytics / Tag Manager

To build the web artifacts with Google Analytics tracking properly configured, the Reserve
tracking ID must be supplied in `.env`. ReactGA/GTM is wired up to click events automatically, but only
the web targets initialize ReactGA/GTM. reserve-wheels is expected to initialize ReactGA/GTM correctly
itself to avoid multiple initializations.

**NOTE:** ReactGA/GTM is bundled with the web artifacts.

## Building

rsv-nav builds two kinds of artifacts: a web artifact which can by included in a page
using standard `<script>` tags, or a Node artifact that can be imported into other
Node projects. To build both artifacts at once:

```
$ yarn build
```

The `build` target will also clean the `dist/` directory before building the new
artifacts. For this reason, it's generally the best target to use.

### Shopify and Drupal

To produce a web artifact for use in Shopify or Drupal:

```
$ yarn build:web
```

The component will look for a mount point with the ID `rsv-nav-menu`.

Ensure that the parent has `position: relative;` and add these styles to the mount point for sticky capability on the primary nav:

```css
#rsv-nav-menu {
  position: sticky;
  top: 0px;
  padding: 0 25px;
}

#rsv-footer-menu {
  width: 100%;
}
```

#### The Web Artifacts

Because the menu data is packaged with the web artifacts, a new version of the web artifacts
must be built when menu changes are made in Prismic.

### reserve-wheels

To product a Node compatible artifact:

```
$ yarn build:node
```

Type declaration files will be generated automatically.

## Using reserve-nav

### Shopify

Below is a suggested workflow for updating megapipe-theme to a new release of
rsv-nav:

_Note:_ Shopify only uses the en-US version of the menu. No other locales are needed.

For Online Store 2.0 themes - this theme included - you'll need to use the [Shopify CLI](https://shopify.dev/themes/tools/cli/getting-started). Get this running, authenticate to the store and continue below.

```sh
# build rsv-nav
~/D/rsv-nav $ yarn build # or yarn build-web

# get the theme to work on locally.
~/D/megapipe-theme $ shopify theme pull

# start Shopify CLI to sync and serve the theme locally
~/D/megapipe-theme $ shopify theme serve

# Remove existing version of rsv-nav-menu
~/D/megapipe-theme $ rm assets/rsv-nav-menu.[contenthash].js

# Copy new artifact into the project
~/D/megapipe-theme $ cp ../reserve-nav/dist/web/rsv-nav-menu.[contenthash].js assets/
```

**Important:** Remember to update the asset URL in `layout/theme.liquid`.

### reserve-wheels (or other Node project)

Simply install the `@scb-dmc/reserve-nav` package and import it as normal:

```jsx
import { NavMenu } from "@scb-dmc/reserve-nav";

const MyPage = () => {
  return (
    <Layout>
      <NavMenu
        menus={menuData}
        imagePreprocessor={imagePreprocessor}
      />
    </Layout>
  );
};

export default MyPage;
```

`@scb-dmc/reserve-nav` exports an object `MenuUtilities` with the following functions:

- `getNavMenuData` - transform Prismic response data into menu data
- `withNavMenuLinkUrls` - Serializes Prismic Document links in menu data

For example:

```jsx
import { MenuUtilities } from "@scb-dmc/reserve-nav";

const client = Prismic.client(process.env.SCB_PRISMIC_URL, {
  accessToken: process.env.SCB_PRISMIC_TOKEN,
});

const getSiteHeaderData = async (prismicClient) => {
  return prismicClient
    .query(
      Prismic.Predicates.at("document.type", "primary_site_navigation_menu")
    )
    .then((response) =>
      MenuUtilities.getNavMenuData(
        MenuUtilities.withNavMenuLinkUrls(response.results[0])
      )
    );
};
```

### Maintainer Publish

Remember to bump versions and build before publishing.

```sh
npm version
yarn build
yarn publish
```