navigation

> Note: this is a "labs" component. While functional, these tasks are prerequisites to promotion to BrightspaceUI "official" status:
>
> - [ ] Design organization buy-in
> - [ ] Architectural sign-off
> - [x] Continuous integration
> - [x] Cross-browser testing
> - [x] Unit tests (if applicable)
> - [x] Accessibility tests
> - [x] Visual diff tests
> - [ ] Localization with Serge (if applicable)
> - [x] Demo page
> - [x] README documentation

A series of web components for top level navigation use in D2L applications.

Installation

``shell
npm install @brightspace-ui-labs/navigation
`

!screenshot of sample usage

Usage: Primary Components

> These are the components that should be used in the VAST MAJORITY of use cases

$3

Add the d2l-navigation component, and provide sub elements d2l-navigation-main-header & d2l-navigation-main-footer (along with their respective slot contents).

`html


Relevant CSS class name:
* --d2l-navigation-shadow-drop-border-display: The default value is block, but this property can be used to hide the shadow by setting it to none.

$3

Add the d2l-navigation-immersive component, providing values for the backLinkHref & backLinkText. Additionally, you may override any of the 3 slots (left, middle, right).
Please note that overridding the left slot will prevent the Back link from displaying. This should only be done in very specialized cases.

`html


- The max-width can be configured to match the max-width used by the LE by setting widthType to normal
- Overflow can be enabled to facilitate components like dropdowns by including the allow-overflow boolean attribute
- A shorter version of the back text can be provided by setting the back-link-text-short attribute

Secondary Components

> These are the components that make up the Primary Components. There might be an edge case or two where it makes sense to use one of these in isolation,
> but PLEASE STRONGLY CONSIDER using a Primary Component instead.

$3

!screenshot of navigation band

`html



`

The d2l-navigation-band also includes a slot with a custom scrollbar and fading effects, but this has only been designed for the d2l-organization-consortium-tabs and should not be used for anything else right now.

Relevant CSS class name:
* --d2l-branding-primary-color: Used to customize the colour of the top navigation band.
* --d2l-navigation-band-slot-height: When using the slot, this is needed to setup the proper scrollbar and fading effects.

---

$3

Add the d2l-navigation-main-header component, and provide elements for the left and right slots.

!screenshot of navigation main header

`html


* left (required): Secondary content (that will shrink with page size) oriented on the left side of the centre gutter (whitespace)
* right (required): Primary content (that will not shrink with page size) oriented on the right side of the centre gutter (whitespace)

---

$3

Add the d2l-navigation-main-footer component, and provide elements for the main slot.

!screenshot of navigation main footer

`html


* main (required): Primary content of the footer. The footer will change in size to accommodate its contents

---

$3

(Placeholder for now)

Relevant CSS class name:
* --d2l-navigation-primary-color: Used to customize the hover colour of the highlight links and buttons

---

$3

provides a button with an icon and optional text.

$3

| Property | Type | Description |
|--|--|--|
| disabled | Boolean | Disables the button |
| text | String, required | Text for the button |
| icon | String | Preset icon key (e.g. tier1:gear) |
| no-highlight-border | Boolean | Visually hides the highlight border when hovered/focused |
| text-hidden | Boolean | Visually hides the text |
| tooltip-position | String | Position of the tooltip ( top\|bottom\|left\|right ); default is bottom |

---

$3

Similar to , a link that comes with an icon and optional text.

!screenshot of navigation link icon

$3

| Property | Type | Description |
|--|--|--|
| href | String, required | URL or URL fragment of the link |
| text | String, required | Text for the button |
| icon | String | Preset icon key (e.g. tier1:gear) |
| text-hidden | Boolean | Visually hides the text |

---

$3

!screenshot of default navigation iterator

`html



`

There is only one slot, and the default button text can be hidden with hide-text.

!screenshot of navigation iterator with hidden iterator button text and custom content

`html

User 1 of 17

`

The iterator button labels can be customized with previous-text and next-text.

!screenshot of navigation iterator with hidden iterator button text and custom content

`html

`

The iterator buttons can be hidden completely with no-next or no-previous.

!screenshot of navigation iterator with no next button
!screenshot of navigation iterator with no previous button

`html


`

Developing and Contributing

After cloning the repo, run npm install to install dependencies.

$3

To run the full suite of tests:

`shell
npm test
`

Alternatively, tests can be selectively run:

`shell


unit tests

`shell
npm start
`

$3

This repo is configured to use semantic-release. Commits prefixed with fix: and feat: will trigger patch and minor releases when merged to main`.

To learn how to create major releases and release from maintenance branches, refer to the semantic-release GitHub Action documentation.