@ongov/ontario-design-system-component-library 6.0.0-alpha.4 → 6.0.0-alpha.5

package/src/components/ontario-header-overflow-menu/ontario-header-overflow-menu.scss

@@ -0,0 +1,103 @@
+@use 'sass:math';
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/global.variables' as globalVariables;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/spacing.variables' as spacing;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/colours.variables' as colours;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/breakpoints.variables' as breakpoints;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/fonts.variables' as fonts;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/2-tools/functions/global.functions' as
+	globalFunctions;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/font-weights.variables' as fontWeights;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/2-tools/placeholder/focus.placeholders' as
+	focusPlaceholders;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/z-index.variables' as zIndex;
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/1-variables/typography.variables';
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/5-layout/_grid.layout.scss';
+@use 'pkg:@ongov/ontario-design-system-global-styles/dist/styles/scss/7-overrides/_visibility.overrides.scss';
+@use '../../styles/header.scss';
+
+$navigation-link-bg--hover: #e5e5e5;
+$ontario-navigation-link-padding-vertical: globalFunctions.px-to-rem(10);
+$ontario-header-overflow-menu-link-font-size: globalFunctions.px-to-rem(18);
+$border-width-1: 1px;
+$border-width-6: 6px;
+
+.ontario-application-navigation {
+	@extend %ontario-application-navigation;
+
+	ul {
+		list-style: none;
+		padding: spacing.$spacing-2 spacing.$spacing-0;
+		margin: spacing.$spacing-0;
+		border-bottom: $border-width-1 solid colours.$ontario-greyscale-20;
+
+		@media screen and (min-width: breakpoints.$medium-breakpoint) {
+			border-bottom: none;
+		}
+	}
+
+	li {
+		border-top: $border-width-1 solid colours.$ontario-greyscale-20;
+		padding: spacing.$spacing-0;
+		margin-bottom: spacing.$spacing-0;
+
+		&:last-of-type {
+			border-bottom: $border-width-1 solid colours.$ontario-greyscale-20;
+		}
+	}
+
+	a {
+		color: colours.$ontario-colour-black;
+		display: block;
+		font-size: $ontario-header-overflow-menu-link-font-size;
+		font-weight: fontWeights.$ontario-font-weights-semi-bold;
+		font-family: fonts.$ontario-font-open-sans;
+		text-decoration: none;
+		padding: $ontario-navigation-link-padding-vertical spacing.$spacing-5;
+
+		&:hover {
+			text-decoration: underline;
+			background-color: $navigation-link-bg--hover;
+		}
+
+		&:active {
+			text-decoration: underline;
+			background-color: colours.$ontario-greyscale-20;
+		}
+
+		&:focus,
+		&:active {
+			@extend %ontario-focus;
+			box-shadow: focusPlaceholders.$ontario-focus-box-shadow inset;
+		}
+
+		&.ontario-link--active {
+			border-left: $border-width-6 solid colours.$ontario-colour-black;
+			background-color: colours.$ontario-greyscale-5;
+		}
+	}
+}
+
+.ontario-application-navigation__container {
+	@extend %ontario-application-navigation__container;
+}
+
+.ontario-application-navigation.ontario-navigation--open .ontario-application-navigation__container {
+	background: colours.$ontario-colour-white;
+	visibility: visible;
+	transform: translateY(0);
+	transition: transform 0.4s ease-in-out;
+
+	@media screen and (min-width: breakpoints.$medium-breakpoint) {
+		transition: none;
+		display: block;
+	}
+}
+
+.ontario-application-navigation.ontario-navigation--open {
+	background: colours.$ontario-colour-white;
+	z-index: zIndex.$ontario-z-index-above-high;
+
+	@media screen and (max-width: breakpoints.$medium-breakpoint) {
+		z-index: zIndex.$ontario-z-index-above-medium; // behind header for animation purposes
+	}
+}

package/src/components/ontario-header-overflow-menu/ontario-header-overflow-menu.tsx

@@ -0,0 +1,249 @@
+import { Component, Prop, State, Watch, h, Listen, Element } from '@stencil/core';
+import { MenuItem } from '../../utils/common/common.interface';
+import { generateMenuItem } from '../../utils/components/header/header-menu-items';
+import { convertStringToBoolean } from '../../utils/helper/utils';
+
+@Component({
+	tag: 'ontario-header-overflow-menu',
+	styleUrl: 'ontario-header-overflow-menu.scss',
+	shadow: true,
+})
+export class OntarioHeaderOverflowMenu {
+	@Element() el: HTMLElement;
+
+	/**
+	 * The items that will go inside the menu.
+	 *
+	 *  @example
+	 * 	<ontario-header-overflow-menu
+	 *			menu-items='[{
+	 *				"title": "Link 1",
+	 *				"href": "/link-1"
+	 *				"linkIsActive": "false"
+	 *			},{
+	 *				"title": "Link 2",
+	 *				"href": "/link-2"
+	 *				"linkIsActive": "false"
+	 *			},{
+	 *				"title": "Link 3",
+	 *				"href": "/link-3"
+	 *				"linkIsActive": "false"
+	 *			},{
+	 *				"title": "Link 4",
+	 *				"href": "/link-4"
+	 *				"linkIsActive": "false"
+	 *			}]'>
+	 *	</ontario-header-overflow-menu>
+	 */
+	@Prop() menuItems: MenuItem[] | string;
+
+	/**
+	 * The `menuItems` are reassigned to `menuItemState` for parsing by `parseMenuItems()`.
+	 */
+	@State() private menuItemState: MenuItem[];
+
+	/**
+	 * A state variable to determine whether the menu is open or not.
+	 *
+	 * The boolean values map to eitherthe presence (true) or absense (false)
+	 * of the `ontario-navigation--open` on the `nav` element.
+	 *
+	 * Triggered by either the `menuButtonToggled` event or the `click` event.
+	 */
+	@State() private menuIsOpen: boolean = false;
+
+	/**
+	 * The current index of the menu item that is focused.
+	 */
+	private currentIndex: number | undefined = undefined;
+
+	/**
+	 * Resets the `currentIndex` value.
+	 *
+	 * Typically resets when the menu closes.
+	 */
+	private resetCurrentIndex() {
+		this.currentIndex = undefined;
+	}
+
+	/**
+	 * Updates the `currentIndex` value.
+	 *
+	 * Typically occurs when a user uses the keyboard to tab through
+	 * menu items.
+	 */
+	private updateCurrentIndex(index: number) {
+		this.currentIndex = index;
+	}
+
+	@Watch('menuItems')
+	parseMenuItems() {
+		if (!Array.isArray(this.menuItems) && typeof this.menuItems === 'string') {
+			let copyOfMenuItems = JSON.parse(this.menuItems) as MenuItem[];
+			// convert stringified boolean values for linkIsActive, to their actual boolean equivalents
+			copyOfMenuItems.forEach((menuItem) =>
+				typeof menuItem?.linkIsActive === 'string'
+					? (menuItem.linkIsActive = convertStringToBoolean(menuItem?.linkIsActive))
+					: menuItem?.linkIsActive,
+			);
+			this.menuItemState = copyOfMenuItems;
+		} else {
+			this.menuItemState = this.menuItems;
+		}
+
+		const activeLinkSet = this.menuItemState?.some((menuItem) => menuItem?.linkIsActive) ?? [];
+
+		// If no active link is set, try to guess and set the active link based
+		// on if the href is included in the URL.
+		if (!activeLinkSet) {
+			const copyOfMenuItemsState = [...this.menuItemState];
+			copyOfMenuItemsState.forEach((menuItem) => {
+				const sanitizedSlug = menuItem.href.replace(/\s+/g, '-').toLowerCase();
+				menuItem.linkIsActive = window.location.pathname.includes(sanitizedSlug);
+			});
+
+			this.menuItemState = [...copyOfMenuItemsState];
+		}
+	}
+
+	/**
+	 * This listens for the `menuButtonToggled` event sent from the header menu button when it is clicked.
+	 * It is used to toggle menu visibility by adding or removing the ontario-navigation--open class on the nav element.
+	 */
+	@Listen('menuButtonToggled', { target: 'window' })
+	toggleMenuVisibility(event: CustomEvent<boolean>) {
+		this.menuIsOpen = event.detail;
+		this.resetCurrentIndex();
+	}
+
+	/**
+	 * Listens for clicks on anything outside of the menu.
+	 * If a click is outside of the menu, then the menu will
+	 * close.
+	 */
+	@Listen('click', { capture: true, target: 'window' })
+	handleClick(event: PointerEvent) {
+		// if the menu (ref) is clicked, return
+		if (event.composedPath().includes(this.menu)) {
+			this.menuIsOpen = true;
+			return;
+		}
+
+		this.menuIsOpen = false;
+		this.resetCurrentIndex();
+	}
+
+	/**
+	 * Listens for keydown events and handles navigation within the menu using the ArrowUp and ArrowDown keys.
+	 */
+	@Listen('keydown', { target: 'window' })
+	handleKeyDown(event: KeyboardEvent) {
+		if (this.menuIsOpen) {
+			const focusableElements: NodeListOf<HTMLElement> = this.menu.querySelectorAll('.ontario-menu-item');
+
+			switch (event.key) {
+				case 'ArrowDown':
+					event.preventDefault();
+					if (this.currentIndex === -1 || this.currentIndex === undefined) {
+						this.currentIndex = 0;
+					} else {
+						this.currentIndex = (this.currentIndex + 1) % focusableElements.length;
+					}
+					focusableElements[this.currentIndex].focus();
+					/**
+					 * Tried other ways of triggering this function to condense code via a watch on currentIndex,
+					 * and also tried sticking at the bottom of the switch's parent if statement.
+					 *
+					 * Both attempts led to inconsistent results (e.g. the aria message was out of sync with currentIndex)
+					 * or just didn't appear at all. Setting this at the source seems to have the best outcome.
+					 */
+					this.updateAriaLive(this.currentIndex);
+					break;
+				case 'ArrowUp':
+					event.preventDefault();
+					if (this.currentIndex === -1 || this.currentIndex === undefined) {
+						this.currentIndex = focusableElements.length - 1;
+					} else {
+						this.currentIndex = (this.currentIndex - 1 + focusableElements.length) % focusableElements.length;
+					}
+					focusableElements[this.currentIndex].focus();
+					this.updateAriaLive(this.currentIndex);
+					break;
+				case 'Tab':
+					focusableElements.forEach((element, index) => {
+						// within an event listener, the scope of "this" changes.
+						// To continue keeping the scope global, set a variable that captures it
+						// Without this, calls to global variables/methods/functions will not work
+						const self = this;
+						if (
+							!element.hasAttribute('data-has-focus-listener') ||
+							element.getAttribute('data-has-focus-listener') === 'false'
+						) {
+							element.addEventListener('focus', () => self.updateCurrentIndex(index));
+							element.setAttribute('data-has-focus-listener', 'true');
+						}
+					});
+					break;
+			}
+		}
+	}
+
+	/**
+	 * Updates the aria-live region with the menu item count and selected option.
+	 *
+	 * @param {number} selectedIndex The index of the selected menu item
+	 */
+	private updateAriaLive(selectedIndex: number) {
+		const menuItemCount = this.menuItemState.length;
+		// index starts at 0, but users expect the message to start at 1
+		// therefore add value of +1 to each index value to align with
+		// user expectations
+		const selectedMenuItemNumber = selectedIndex + 1;
+		const ariaLiveMessage = `Option ${selectedMenuItemNumber} of ${menuItemCount}`;
+
+		if (this.ariaLiveRegion) {
+			this.ariaLiveRegion.textContent = ariaLiveMessage;
+		}
+	}
+
+	componentWillLoad() {
+		this.parseMenuItems();
+	}
+
+	/**
+	 * Assigning values to elements to use them as ref
+	 */
+	private menu!: HTMLElement;
+
+	/**
+	 * The aria-live region that will be updated with the selected menu item.
+	 */
+	private ariaLiveRegion!: HTMLElement;
+
+	render() {
+		return (
+			<nav
+				role="navigation"
+				class={
+					this.menuIsOpen ? 'ontario-application-navigation ontario-navigation--open' : 'ontario-application-navigation'
+				}
+				id="ontario-application-navigation"
+				ref={(el) => (this.menu = el as HTMLElement)}
+			>
+				<div class="ontario-application-navigation__container">
+					<ul>
+						{this.menuItemState?.map((item: MenuItem) => {
+							return generateMenuItem(item.href, item.title, item.linkIsActive);
+						})}
+					</ul>
+				</div>
+				<div
+					id="aria-live-region"
+					class="ontario-show-for-sr"
+					aria-live="polite"
+					ref={(el) => (this.ariaLiveRegion = el as HTMLElement)}
+				></div>
+			</nav>
+		);
+	}
+}

package/src/components/ontario-header-overflow-menu/readme.md

@@ -0,0 +1,133 @@
+import { OntarioHeaderOverflowMenu } from '@ongov/ontario-design-system-component-library-react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# ontario-header-overflow-menu
+
+This component is intended to be used as a sub-component of the [ontario-header](../ontario-header) component.
+
+## Configuration
+
+Once the component package has been installed (see Ontario Design System Component Library for installation instructions), the ontario-header-overflow-menu component can be added directly into the project's code, and can be customized by updating the properties outlined [here](#properties). Please see the [examples](#examples) below for how to configure the component.
+
+## Examples
+
+```html
+<ontario-header-menu-overflow
+	menu-items='[
+    {
+      "title":"Item 1",
+      "href":"/item-1"
+    },
+    {
+      "title":"Item 2",
+      "href":"/item-2"
+    },
+    {
+      "title":"Item 3",
+      "href":"/item-3"
+    },
+    {
+      "title":"Item 4",
+      "href":"/item-4"
+    },
+  ]'
+	trap-menu-focus="false"
+>
+</ontario-header-menu-overflow>
+```
+
+<div>
+    <OntarioHeaderMenuOverflow
+    menu-items='[
+      {
+        "title":"Item 1",
+        "href":"/item-1"
+      },
+      {
+        "title":"Item 2",
+        "href":"/item-2"
+      },
+      {
+        "title":"Item 3",
+        "href":"/item-3"
+      },
+      {
+        "title":"Item 4",
+        "href":"/item-4"
+      },
+    ]'
+    trap-menu-focus='false'
+  >
+  </OntarioHeaderMenuOverflow>
+</div>
+
+## Custom property types
+
+### menuItems
+
+The menu items you want to display in the dropdown menu button.
+
+If `linkIsActive` is not set on a menu item, the component will attempt to set the property on a menu item, based on if it's `href` value is included within the URL. If `linkIsActive` is set, it will take **precendence** over the `href` being included within the URL.
+
+If `maxSubheaderLinks` is set within `applicationHeaderInfo` on the `ontario-header` component for an `application` type header, some of these links will be dispersed as links within the subheader menu bar relative to the breakpoint and number set.
+
+```html
+<ontario-header
+	menu-items='[ 
+		{ 
+			"title": "Vehicle registration",
+			"href": "/vehicle-registration",
+			"linkIsActive": "false" 
+		}, 
+		{ 
+			"title": "Driver records",
+			"href": "/driver-records", 
+			"linkIsActive": "false" 
+		}, 
+		{ 
+			"title": "Accessible Parking Permits", 
+			"href": "/accessible-parking-permits", 
+			"linkIsActive": "false" 
+		}, 
+		{ 
+			"title": "Highway traveler information", 
+			"href": "/highway-traveler-information", 
+			"linkIsActive": "true",
+			"onClickHandler": (e: Event) => { e.preventDefault(); alert("Menu item clicked!") }
+		} 
+	]'
+></ontario-header>
+```
+
+| **Property name** | **Type**                 | **Description**                                                                                                                                     |
+| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`           | `string`                 | The title of the menu item (this is what will appear as the label in the header/dropdown menu)                                                      |
+| `href`            | `string`                 | The URL for the menu item                                                                                                                           |
+| `linkIsActive`    | `boolean`                | A boolean flag for whether or not the current menu item link is active. If set to true, active classes and styles will be applied to the menu item. |
+| `onClickHandler`  | `(event: Event) => void` | An optional custom function to add to the menu item. This can be used if any additional logic should happen when the menu item is clicked.          |
+
+<!-- Auto Generated Below -->
+
+## Properties
+
+| Property    | Attribute    | Description                             | Type                   | Default     |
+| ----------- | ------------ | --------------------------------------- | ---------------------- | ----------- |
+| `menuItems` | `menu-items` | The items that will go inside the menu. | `MenuItem[] \| string` | `undefined` |
+
+## Dependencies
+
+### Used by
+
+- [ontario-header](../ontario-header)
+
+### Graph
+
+```mermaid
+graph TD;
+  ontario-header --> ontario-header-overflow-menu
+  style ontario-header-overflow-menu fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+---
+
+_Built with [StencilJS](https://stenciljs.com/)_

package/src/components/ontario-header-overflow-menu/test/__snapshots__/ontario-header-overflow-menu.spec.tsx.snap

@@ -0,0 +1,25 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`ontario-header-overflow-menu should render menu items correctly 1`] = `
+<ontario-header-overflow-menu>
+  <template shadowrootmode="open">
+    <nav class="ontario-application-navigation" id="ontario-application-navigation" role="navigation">
+      <div class="ontario-application-navigation__container">
+        <ul>
+          <li>
+            <a class="ontario-menu-item" href="/link-1">
+              Link 1
+            </a>
+          </li>
+          <li>
+            <a class="ontario-menu-item" href="/link-2">
+              Link 2
+            </a>
+          </li>
+        </ul>
+      </div>
+      <div aria-live="polite" class="ontario-show-for-sr" id="aria-live-region"></div>
+    </nav>
+  </template>
+</ontario-header-overflow-menu>
+`;

package/src/components/ontario-header-overflow-menu/test/ontario-header-overflow-menu.e2e.tsx

@@ -0,0 +1,20 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('ontario-header-overflow-menu', () => {
+	it('should handle menu toggle correctly', async () => {
+		const page = await newE2EPage();
+		await page.setContent('<ontario-header-overflow-menu></ontario-header-overflow-menu>');
+
+		const component = await page.find('ontario-header-overflow-menu');
+
+		// Simulate clicking the toggle button
+		const button = await page.find('ontario-header-overflow-menu >>> button');
+		expect(button).not.toBeNull(); // Ensure button exists
+
+		await button.click();
+		await page.waitForChanges();
+
+		const menuIsOpen = await component.getProperty('menuIsOpen');
+		expect(menuIsOpen).toBe(true);
+	});
+});

package/src/components/ontario-header-overflow-menu/test/ontario-header-overflow-menu.spec.tsx

@@ -0,0 +1,125 @@
+import { newSpecPage, SpecPage } from '@stencil/core/testing';
+import { OntarioHeaderOverflowMenu } from '../ontario-header-overflow-menu';
+
+describe('ontario-header-overflow-menu', () => {
+	let page: SpecPage;
+	let host: HTMLOntarioHeaderOverflowMenuElement;
+	let hostInstance: any | OntarioHeaderOverflowMenu;
+	let hostShadow: ShadowRoot;
+
+	beforeEach(async () => {
+		page = await newSpecPage({
+			components: [OntarioHeaderOverflowMenu],
+			html: `<ontario-header-overflow-menu></ontario-header-overflow-menu>`,
+		});
+
+		host = page.root as HTMLOntarioHeaderOverflowMenuElement;
+		hostInstance = page.rootInstance as OntarioHeaderOverflowMenu;
+		hostShadow = host.shadowRoot as ShadowRoot;
+
+		await page.waitForChanges();
+	});
+
+	it('should render without errors', async () => {
+		expect(host).not.toBeNull();
+		expect(host.tagName).toBe('ONTARIO-HEADER-OVERFLOW-MENU');
+
+		expect(hostShadow).not.toBeNull();
+	});
+
+	it('should render menu items correctly', async () => {
+		const menuItems = [
+			{ title: 'Link 1', href: '/link-1', linkIsActive: false },
+			{ title: 'Link 2', href: '/link-2', linkIsActive: false },
+		];
+
+		host.menuItems = menuItems;
+
+		await page.waitForChanges();
+
+		// Check if the menuItem data is set correctly in the menu overflow component
+		// Should match the number of menu items set in the cosntant above
+		expect(host.menuItems.length).toBe(2);
+
+		const overflowMenuRenderedMenuItems = hostShadow.querySelectorAll(
+			'.ontario-menu-item',
+		) as NodeListOf<HTMLAnchorElement>;
+
+		// Check to see the HTML output of the rendered menu items is as expected
+		expect(overflowMenuRenderedMenuItems.length).toBe(2);
+		expect(overflowMenuRenderedMenuItems[0].textContent).toBe(menuItems[0].title);
+		expect(overflowMenuRenderedMenuItems[0].getAttribute('href')).toBe(menuItems[0].href);
+		expect(overflowMenuRenderedMenuItems[1].textContent).toBe(menuItems[1].title);
+		expect(overflowMenuRenderedMenuItems[1].getAttribute('href')).toBe(menuItems[1].href);
+
+		expect(host).toMatchSnapshot();
+	});
+
+	/* This is a good test but may be better suited as an E2E test where actual browser behaviour is tested */
+	it('should toggle menu open when the menuButtonToggled event is received', async () => {
+		const menuItems = [
+			{ title: 'Link 1', href: '/link-1', linkIsActive: false },
+			{ title: 'Link 2', href: '/link-2', linkIsActive: false },
+		];
+
+		host.menuItems = menuItems;
+
+		await page.waitForChanges();
+
+		expect(hostInstance.menuIsOpen).toBe(false);
+
+		// Simulate the menu button being toggled open
+		const event = new CustomEvent('menuButtonToggled', { detail: true });
+		window.dispatchEvent(event);
+
+		await page.waitForChanges();
+
+		expect(hostInstance.menuIsOpen).toBe(true);
+	});
+
+	/* This is a good test but may be better suited as an E2E test where actual browser behaviour is tested */
+	it('should toggle menu closed when the menuButtonToggled event is received', async () => {
+		const menuItems = [
+			{ title: 'Link 1', href: '/link-1', linkIsActive: false },
+			{ title: 'Link 2', href: '/link-2', linkIsActive: false },
+		];
+
+		host.menuItems = menuItems;
+
+		await page.waitForChanges();
+
+		hostInstance.menuIsOpen = true;
+
+		await page.waitForChanges();
+
+		// Simulate the menu button being toggled closed
+		const event = new CustomEvent('menuButtonToggled', { detail: false });
+		window.dispatchEvent(event);
+		await page.waitForChanges();
+
+		expect(hostInstance.menuIsOpen).toBe(false);
+	});
+
+	/* This is a good test but may be better suited as an E2E test where actual browser behaviour is tested */
+	it('should close menu when clicking outside', async () => {
+		const menuItems = [
+			{ title: 'Link 1', href: '/link-1', linkIsActive: false },
+			{ title: 'Link 2', href: '/link-2', linkIsActive: false },
+		];
+
+		host.menuItems = menuItems;
+
+		await page.waitForChanges();
+
+		hostInstance.menuIsOpen = true;
+
+		await page.waitForChanges();
+
+		// Simulate clicking outside the menu
+		const event = new MouseEvent('click', { bubbles: true });
+		document.body.dispatchEvent(event);
+		await page.waitForChanges();
+
+		expect(hostInstance.menuIsOpen).toBe(false);
+	});
+});