NDS-391 in page nav docs (#315)

* NDS-391 Update docs for in-page-nav variant; revert heading ID

* Publish

 - @nice-digital/design-system@5.0.13-alpha.0
 - @nice-digital/nds-in-page-nav@4.0.7-alpha.0
 - @nice-digital/design-system-docs@1.0.13-alpha.0

* NDS-391 Update in-page-nav spacing

---------

Co-authored-by: Chris Barker <chris.barker@nice.org.uk>

components/design-system/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nice-digital/design-system",
-	"version": "5.0.12",
+	"version": "5.0.13-alpha.0",
 	"description": "Your source for quickly creating consistent on-brand NICE digital services",
 	"author": "Ian Routledge <ian.routledge@nice.org.uk>",
 	"homepage": "https://design-system.nice.org.uk/",
@@ -51,7 +51,7 @@
 		"@nice-digital/nds-grid": "^4.0.7",
 		"@nice-digital/nds-hero": "^4.0.6",
 		"@nice-digital/nds-horizontal-nav": "^4.0.6",
-		"@nice-digital/nds-in-page-nav": "^4.0.6",
+		"@nice-digital/nds-in-page-nav": "^4.0.7-alpha.0",
 		"@nice-digital/nds-input": "^4.0.6",
 		"@nice-digital/nds-maintain-ratio": "^4.0.6",
 		"@nice-digital/nds-page-header": "^4.0.6",

components/nds-in-page-nav/README.md

@@ -11,7 +11,10 @@
 			- [headingsContainerSelector](#headingscontainerselector)
 			- [headingsSelector](#headingsselector)
 			- [headingsExcludeSelector](#headingsexcludeselector)
+			- [headingsExcludeContainer](#headingsexcludecontainer)
 			- [scrollTolerance](#scrolltolerance)
+			- [noScroll](#noScroll)
+			- [twoColumns](#twoColumns)
 			- [Other props](#other-props)
 		- [SCSS](#scss)
 		- [HTML](#html)
@@ -68,7 +71,16 @@ A selector for headings to use for the navigation.
 - Type: `string`
 - Default: `""`
 
-A selector for any headigns to exclude from the navigation.
+A selector for any headings to exclude from the navigation.
+
+#### headingsExcludeContainer
+
+- Type: `string`
+- Default: `""`
+
+A selector for a container that will be completely ignored, i.e. all headings
+within that container will be excluded. Useful in cases where it's not easy
+to exclude or select individual headings.
 
 #### scrollTolerance
 
@@ -77,6 +89,20 @@ A selector for any headigns to exclude from the navigation.
 
 The number of pixels from the top of the screen that's used to determine if a heading is considered to current/active.
 
+#### noScroll
+
+- Type: `boolean`
+- Default: `false`
+
+If true, the in-page-nav will no longer scroll along with the user's current position (i.e. it won't be sticky).
+
+#### twoColumns
+
+- Type: `boolean`
+- Default: `false`
+
+If true, the in-page-nav will render as two columns instead of just one. This will only work if `noScroll` is set to `true`.
+
 #### Other props
 
 Any additional props will be spread across the container.

components/nds-in-page-nav/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nice-digital/nds-in-page-nav",
-	"version": "4.0.6",
+	"version": "4.0.7-alpha.0",
 	"description": "In page navigation component for the NICE Design System",
 	"author": "Ian Routledge <ian.routledge@nice.org.uk>",
 	"homepage": "https://design-system.nice.org.uk/",

components/nds-in-page-nav/scss/in-page-nav.scss

@@ -51,6 +51,7 @@
       top: 0;
 
       &--no-scroll {
+        margin: utils.rem(0 0 spacing.$large);
         max-height: none;
         position: relative;
       }
@@ -63,6 +64,7 @@
 
         .in-page-nav--two-columns & {
           columns: 2;
+          column-gap: utils.rem(spacing.$xx-large);
         }
 
         .in-page-nav__list {

components/nds-in-page-nav/src/InPageNav.tsx

@@ -1,6 +1,6 @@
 /* eslint-disable no-mixed-spaces-and-tabs */
 /* eslint-disable indent */
-import React, { useEffect, useState, useId } from "react";
+import React, { useEffect, useState } from "react";
 import throttle from "lodash.throttle";
 
 import { buildLinkTree, getActiveHeadingId, type LinkTreeItem } from "./utils";
@@ -33,7 +33,7 @@ export const InPageNav = ({
 }: InPageNavProps) => {
 	const [activeHeadingId, setActiveHeadingId] = useState<null | string>(null);
 	const [linkTree, setlinkTree] = useState<LinkTreeItem[]>([]);
-	const titleId = useId();
+	const titleId = "inpagenav-title";
 
 	// Build the tree of links from the headings on the page
 	useEffect(() => {

components/nds-in-page-nav/src/__snapshots__/InPageNav.test.tsx.snap

@@ -5,14 +5,14 @@ exports[`InPageNav should match snapshot 1`] = `
   "asFragment": [Function],
   "baseElement": <div>
     <nav
-      aria-labelledby=":r0:"
+      aria-labelledby="inpagenav-title"
       class="in-page-nav"
       data-component="in-page-nav"
       data-track="false"
     >
       <h2
         class="in-page-nav__title"
-        id=":r0:"
+        id="inpagenav-title"
       >
         On this page
       </h2>
@@ -52,14 +52,14 @@ exports[`InPageNav should match snapshot 1`] = `
   </div>,
   "container": <div>
     <nav
-      aria-labelledby=":r0:"
+      aria-labelledby="inpagenav-title"
       class="in-page-nav"
       data-component="in-page-nav"
       data-track="false"
     >
       <h2
         class="in-page-nav__title"
-        id=":r0:"
+        id="inpagenav-title"
       >
         On this page
       </h2>

docs/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nice-digital/design-system-docs",
-	"version": "1.0.12",
+	"version": "1.0.13-alpha.0",
 	"private": true,
 	"scripts": {
 		"dev": "next dev",
@@ -13,7 +13,7 @@
 		"@mdx-js/loader": "^2.1.5",
 		"@mdx-js/react": "^2.1.5",
 		"@next/mdx": "^13.0.1",
-		"@nice-digital/design-system": "^5.0.12",
+		"@nice-digital/design-system": "^5.0.13-alpha.0",
 		"@nice-digital/global-nav": "^5.0.916",
 		"glob": "^8.0.3",
 		"next": "^13.2.4",

docs/pages/components/in-page-nav.mdx

@@ -64,12 +64,18 @@ If you're using the React component, the "On this page" heading will be added fo
 
 ### Positioning
 
-The in-page navigation sits on the right-hand side of the page on large screen sizes.
-
-It stacks below the main page title and above the main page content on mobile devices and small screens.
+The in-page navigation sits on the right-hand side of the page on large screen sizes. It stacks below the main page title and above the main page content on mobile devices and small screens.
 
 The menu should sit outside other content, such as hero elements, panels, full bleed and alerts.
 
+#### No-scroll variant
+
+If you don't want the menu to be sticky (i.e. scroll along with the page), you can use its `noScroll` variant. This is useful if you want a list of links to sit directly above other content, for example in the main body of the page.
+
+#### Two columns
+
+If you're using the no-scroll variant, you can also choose to render the menu in two columns instead of one.
+
 ### Content
 
 The menu uses headings from the page to generate link text. This is to ensure the link and the content match up. It helps to reassure users that they have been moved to the right part of the page.
@@ -103,7 +109,10 @@ The basic version of the in-page-nav only requires the below data attribute to i
 | Headings container selector| `data-in-page-nav-headings-container-selector` | This is a CSS-style selector for the scope of the page that you want the in-page-nav to use as its context.| `main`| `<div data-in-page-nav data-in-page-nav-headings-container-selector='.my-container'></div>`|
 | Headings to include| `data-in-page-nav-headings-selector` | Control for which headings you'd like to be included in the navigation. Defaults to `h2` and `h3`. | `h2, h3` | `<div data-in-page-nav data-in-page-nav-headings-selector='h4, h5'></div>`|
 | Headings to exclude| `data-in-page-nav-headings-exclude-selector` | Any CSS-style selectors you'd like to exclude. | none | `<div data-in-page-nav data-in-page-nav-headings-exclude-selector='.exclude-me-from-nav'></div>`|
+| Container to exclude| `data-in-page-nav-headings-exclude-container` | A CSS-style selector that will exclude any headings contained within it. | none | `<div data-in-page-nav data-in-page-nav-headings-exclude-container='.exclude-everything-in-me-from-nav'></div>`|
 | Scroll tolerance| `data-in-page-nav-scroll-tolerance` | This is a pixel value to determine how close to the top of the viewport a heading has to be in order to be considered "active" and therefore highlighted. | `50` | `<div data-in-page-nav data-in-page-nav-scroll-tolerance='100'></div>`|
+| No scroll | `data-in-page-nav-no-scroll` | A boolean (i.e. true/false) value that will determine whether to show the no-scroll variant | `false` | `<div data-in-page-nav data-in-page-nav-no-scroll='true'></div>`|
+| Two columns | `data-in-page-nav-two-columns` | A boolean (i.e. true/false) value that will determine whether to show the two columns variant | `false` | `<div data-in-page-nav data-in-page-nav-two-columns='true'></div>`|
 -----------