npm - @ongov/ontario-design-system-component-library - Versions diffs - 4.3.0 → 4.3.1-alpha.1 - Mend

@ongov/ontario-design-system-component-library 4.3.0 → 4.3.1-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/src/components/ontario-language-toggle/ontario-language-toggle.tsx CHANGED Viewed

@@ -1,10 +1,12 @@
 import { Component, Prop, State, Event, EventEmitter, Watch, h, Fragment } from '@stencil/core';
-import { Language } from '../../utils/common/language-types';
-import { validateLanguage } from '../../utils/validation/validation-functions';
+import { supportedLanguages, Language } from '../../utils/common/language-types';
 import { default as translations } from '../../translations/global.i18n.json';
 import { HeaderLanguageToggleEventDetails } from '../../utils/events/common-events.interface';
+import { validateValueAgainstArray } from '../../utils/validation/validation-functions';
+import { ConsoleMessageClass } from '../../utils/console-message/console-message';
+import { printArray, getRootHTMLElement } from '../../utils/helper/utils';
 @Component({
 	tag: 'ontario-language-toggle',
@@ -12,7 +14,14 @@ import { HeaderLanguageToggleEventDetails } from '../../utils/events/common-even
 	shadow: true,
 })
 export class OntarioLanguageToggle {
-	@Prop({ mutable: true }) language: Language | string;
+	/**
+	 * The language of the component.
+	 *
+	 * In most cases, the language toggle should be the source of truth for determining the site language.
+	 *
+	 * Only pass a language value here if necessary.
+	 */
+	@Prop({ mutable: true }) language?: Language;
 	/**
 	 * The size of the language toggle button.
@@ -38,89 +47,227 @@ export class OntarioLanguageToggle {
 	@State() translations: any = translations;
 	/**
-	 * An event to set the Document's HTML lang property, and emit the toggled language to other components.
+	 * Internal state used as the source of truth for component language.
+	 */
+	@State() private languageState: Language;
+	/**
+	 * Internal state used to render the text on the language toggle UI.
+	 */
+	@State() private oppositeLanguageLabel: { fullWord: string; abbreviation: Language } | undefined = undefined;
+	/**
+	 * Updates the language and languageState props when changes to the language prop are detected.
 	 */
-	@Event() setAppLanguage: EventEmitter<string>;
-	setAppLanguageHandler() {
-		let lang: string | Language;
+	@Watch('language')
+	updateLanguage() {
 		if (this.language) {
-			lang = this.language;
-		} else if (document.documentElement.lang) {
-			lang = document.documentElement.lang;
-		} else {
-			lang = 'en';
+			if (!validateValueAgainstArray(this.language, supportedLanguages)) {
+				this.showLanguageWarning(this.language);
+				this.language = this.translations.siteLanguage.abbreviation.en as Language;
+			}
+			this.languageState = this.language;
 		}
+		this.setAppLanguageHandler();
+	}
+	/**
+	 * Event that fires during the setAppLanguageHandler() method.
+	 *
+	 * The event contains the current language (after language logic has already occurred).
+	 */
+	@Event() setAppLanguage: EventEmitter<Language>;
+	/**
+	 * Event that fires when the language toggle is pressed/clicked.
+	 *
+	 * The event contains the oldLanguage along with the newLanguage.
+	 */
+	@Event() headerLanguageToggled: EventEmitter<HeaderLanguageToggleEventDetails>;
+	/**
+	 * This function sets the languageState (if not already set).
+	 *
+	 * It also emits the setAppLanguage() event, updates the component language label, and
+	 * updates the <html> tag lang attribute with the languageState value.
+	 *
+	 * It gets called by the connectedCallback() component lifecycle hook, and by the
+	 * updateLanguage() method, which is fired on the watch for the language prop.
+	 */
+	private setAppLanguageHandler() {
+		const defaultLang = this.translations.siteLanguage.abbreviation.en;
+		const rootLang = getRootHTMLElement()?.lang;
+		// If languageState is not set, set it equal to the following cadence:
+		// language prop value, <html> tag lang attribute, or default to "en"
+		if (!this.languageState) {
+			if (this.language) {
+				this.languageState = this.language;
+			} else if (rootLang) {
+				if (validateValueAgainstArray(rootLang, supportedLanguages)) {
+					this.languageState = rootLang as Language;
+				} else {
+					this.showLanguageWarning(rootLang, 'document');
+					this.languageState = defaultLang;
+				}
+			} else {
+				this.languageState = defaultLang;
+			}
+		}
+		this.setAppLanguage.emit(this.languageState);
-		this.language = lang;
-		this.setAppLanguage.emit(lang);
+		this.oppositeLanguageLabel = {
+			fullWord: this.getOppositeLanguageFullWord(),
+			abbreviation: this.getOppositeLanguageAbbrievation(),
+		};
-		this.updateHTMLLang(lang);
+		this.updateHTMLLang();
 	}
 	/**
 	 * An event that emits to other components that the language toggle button has been toggled.
+	 *
+	 * @param {Language} oldLanguage - The language prior to the language toggle being pressed.
+	 * @param {globalThis.Event} event - event that triggered the function (e.g. onclick).
 	 */
-	@Event() headerLanguageToggled: EventEmitter<HeaderLanguageToggleEventDetails>;
-	handleHeaderLanguageToggled(language: string, event?: globalThis.Event) {
-		const toggledLanguage = language === 'en' ? 'fr' : 'en';
-		this.language = toggledLanguage;
+	private handleHeaderLanguageToggled(oldLanguage: Language, event?: globalThis.Event) {
+		this.languageState =
+			oldLanguage === this.translations.siteLanguage.abbreviation.en
+				? this.translations.siteLanguage.abbreviation.fr
+				: this.translations.siteLanguage.abbreviation.en;
-		this.headerLanguageToggled.emit({ oldLanguage: language, newLanguage: toggledLanguage });
+		this.headerLanguageToggled.emit({ oldLanguage: oldLanguage, newLanguage: this.languageState });
-		this.updateHTMLLang(toggledLanguage);
+		this.updateHTMLLang();
 		if (this.customLanguageToggle && event) {
 			this.customLanguageToggle(event);
 		}
 	}
-	@Watch('language')
-	updateLanguage() {
-		this.language = validateLanguage(this.language);
-		this.setAppLanguageHandler();
+	/**
+	 * Prints a warning message to the console about using an incorrect language for the component.
+	 *
+	 * @param {string} lang - The incorrect language that was received.
+	 * @param {string} type - prop/document | Where the incorrect language is coming from.
+	 */
+	private showLanguageWarning(lang: string, type: 'prop' | 'document' = 'prop') {
+		const propOrDocumentMessage =
+			type === 'prop' ? `The language prop value of ${lang} ` : `The HTML document lang attribute value of ${lang} `;
+		const message = new ConsoleMessageClass();
+		message
+			.addDesignSystemTag()
+			.addRegularText(propOrDocumentMessage)
+			.addRegularText('is not a valid language value for the ')
+			.addMonospaceText(' <ontario-language-toggle> ')
+			.addRegularText(`component. Valid language values are ${printArray([...supportedLanguages])}. `)
+			.addRegularText(`A default language value of ${this.translations.siteLanguage.abbreviation.en} will be applied.`)
+			.printMessage();
 	}
-	updateHTMLLang = (lang: string) => {
-		const htmlElement = document.firstElementChild;
+	/**
+	 * Returns abbreviated text for the opposite language.
+	 *
+	 * @returns {Language}
+	 */
+	private getOppositeLanguageAbbrievation(): Language {
+		return this.languageState === this.translations.siteLanguage.abbreviation.en
+			? this.translations.siteLanguage.abbreviation.fr
+			: this.translations.siteLanguage.abbreviation.en;
+	}
-		if (htmlElement?.tagName.toLowerCase() === 'html') {
-			if (lang) {
-				htmlElement.setAttribute('lang', lang);
-			} else {
-				htmlElement.setAttribute('lang', 'en');
-			}
-		}
+	/**
+	 * Returns full word text for the opposite language.
+	 *
+	 * @returns {string}
+	 */
+	private getOppositeLanguageFullWord(): string {
+		return this.languageState === this.translations.siteLanguage.abbreviation.en
+			? this.translations.siteLanguage.fullWord.fr
+			: this.translations.siteLanguage.fullWord.en;
+	}
+	/*
+	 * Updates the <html> lang attribute based on component languageState.
+	 */
+	private updateHTMLLang = () => {
+		const htmlElement = getRootHTMLElement();
-		return;
+		if (htmlElement) {
+			htmlElement.setAttribute('lang', this.languageState);
+		}
 	};
+	/**
+	 * Component life cycle hook.
+	 *
+	 * https://stenciljs.com/docs/component-lifecycle#connectedcallback
+	 */
 	connectedCallback() {
-		this.updateLanguage();
+		this.setAppLanguageHandler();
 	}
-	render() {
-		const language = this.language === 'en' ? 'Français' : 'English';
-		const abbreviatedLanguage = this.language === 'en' ? 'FR' : 'EN';
+	/**
+	 * Component life cycle hook.
+	 *
+	 * https://stenciljs.com/docs/component-lifecycle#componentdidload
+	 */
+	componentDidLoad() {
+		/**
+		 * Creates a MutationObserver (a type of watch) on the <html> tag lang attribute.
+		 *
+		 * When changes occur, the oppositeLanguageLabel state variable regenerates.
+		 *
+		 * This is to act as a form of callback and create a subtle delay between page content
+		 * updating and the language toggle label updating.
+		 */
+		const observer = new MutationObserver((mutations) => {
+			mutations.forEach((mutation) => {
+				switch (mutation.type) {
+					case 'attributes':
+						switch (mutation.attributeName) {
+							case 'lang':
+								this.oppositeLanguageLabel = {
+									fullWord: this.getOppositeLanguageFullWord(),
+									abbreviation: this.getOppositeLanguageAbbrievation(),
+								};
+								break;
+						}
+						break;
+				}
+			});
+		});
+		// Only create/trigger the MutationObserver if the <html> element exists.
+		if (getRootHTMLElement()) {
+			const options = { attributes: true };
+			observer.observe(getRootHTMLElement(), options);
+		}
+	}
+	render() {
 		return (
 			<a
+				aria-label={this.translations.languageToggle.ariaLabel[`${this.oppositeLanguageLabel?.abbreviation}`]}
 				class={
 					this.size === 'default'
 						? 'ontario-language-toggler ontario-language-toggler--default'
 						: 'ontario-language-toggler ontario-language-toggler--small'
 				}
 				href={this.url ? this.url : '#'}
-				aria-label={this.translations.languageToggle.ariaLabel[`${this.language}`]}
-				onClick={(e) => this.handleHeaderLanguageToggled(this.language, e)}
+				hreflang={this.oppositeLanguageLabel?.abbreviation}
+				lang={this.oppositeLanguageLabel?.abbreviation}
+				onClick={(e) => this.handleHeaderLanguageToggled(this.languageState, e)}
 			>
 				{this.size === 'small' ? (
-					<span>{language}</span>
+					<span>{this.oppositeLanguageLabel?.fullWord}</span>
 				) : (
 					<Fragment>
-						<abbr title={language} class="ontario-show-for-small-only">
-							{abbreviatedLanguage}
+						<abbr title={this.oppositeLanguageLabel?.fullWord} class="ontario-show-for-small-only">
+							{this.oppositeLanguageLabel?.abbreviation.toUpperCase()}
 						</abbr>
-						<span class="ontario-show-for-medium">{language}</span>
+						<span class="ontario-show-for-medium">{this.oppositeLanguageLabel?.fullWord}</span>
 					</Fragment>
 				)}
 			</a>

package/src/components/ontario-language-toggle/readme.md CHANGED Viewed

@@ -10,19 +10,19 @@ It is used in the ontario-header component.
 ## Properties
-| Property               | Attribute  | Description                                                                                         | Type                                    | Default     |
-| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
-| `customLanguageToggle` | --         | A custom function to pass to the language toggle button. This is optional.                          | `((event: Event) => void) \| undefined` | `undefined` |
-| `language`             | `language` |                                                                                                     | `string`                                | `undefined` |
-| `size`                 | `size`     | The size of the language toggle button. If no prop is passed, it will be set to the `default` size. | `"default" \| "small" \| undefined`     | `'default'` |
-| `url`                  | `url`      | The URL to change to when the language toggle button is clicked. This is optional.                  | `string \| undefined`                   | `undefined` |
+| Property               | Attribute  | Description                                                                                                                                                                      | Type                                    | Default     |
+| ---------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
+| `customLanguageToggle` | --         | A custom function to pass to the language toggle button. This is optional.                                                                                                       | `((event: Event) => void) \| undefined` | `undefined` |
+| `language`             | `language` | The language of the component. In most cases, the language toggle should be the source of truth for determining the site language. Only pass a language value here if necessary. | `"en" \| "fr" \| undefined`             | `undefined` |
+| `size`                 | `size`     | The size of the language toggle button. If no prop is passed, it will be set to the `default` size.                                                                              | `"default" \| "small" \| undefined`     | `'default'` |
+| `url`                  | `url`      | The URL to change to when the language toggle button is clicked. This is optional.                                                                                               | `string \| undefined`                   | `undefined` |
 ## Events
-| Event                   | Description                                                                                           | Type                                            |
-| ----------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `headerLanguageToggled` | An event that emits to other components that the language toggle button has been toggled.             | `CustomEvent<HeaderLanguageToggleEventDetails>` |
-| `setAppLanguage`        | An event to set the Document's HTML lang property, and emit the toggled language to other components. | `CustomEvent<string>`                           |
+| Event                   | Description                                                                                                                                      | Type                                            |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| `headerLanguageToggled` | Event that fires when the language toggle is pressed/clicked. The event contains the oldLanguage along with the newLanguage.                     | `CustomEvent<HeaderLanguageToggleEventDetails>` |
+| `setAppLanguage`        | Event that fires during the setAppLanguageHandler() method. The event contains the current language (after language logic has already occurred). | `CustomEvent<"en" \| "fr">`                     |
 ## Dependencies

package/src/components/ontario-language-toggle/test/__snapshots__/ontario-language-toggle.spec.tsx.snap CHANGED Viewed

@@ -3,7 +3,7 @@
 exports[`ontario-language-toggle snapshot should render the expected html 1`] = `
 <ontario-language-toggle>
   <mock:shadow-root>
-    <a aria-label="Click to switch language to French" class="ontario-language-toggler ontario-language-toggler--default" href="#">
+    <a aria-label="Cliquez pour changer la langue en français" class="ontario-language-toggler ontario-language-toggler--default" href="#" hreflang="fr" lang="fr">
       <abbr class="ontario-show-for-small-only" title="Français">
         FR
       </abbr>

package/src/components/ontario-language-toggle/test/ontario-language-toggle.spec.tsx CHANGED Viewed

@@ -1,5 +1,8 @@
 import { newSpecPage } from '@stencil/core/testing';
 import { OntarioLanguageToggle } from '../ontario-language-toggle';
+import { mutationObserverMock } from '../../../utils/tests/mutation-observer.mock';
+global.MutationObserver = mutationObserverMock;
 describe('ontario-language-toggle', () => {
 	describe('snapshot', () => {
@@ -22,7 +25,7 @@ describe('ontario-language-toggle', () => {
 		expect(page.root).toEqualHtml(`
 			<ontario-language-toggle>
 				<mock:shadow-root>
-					<a aria-label="Click to switch language to French" class="ontario-language-toggler ontario-language-toggler--default" href="#">
+					<a aria-label="Cliquez pour changer la langue en français" class="ontario-language-toggler ontario-language-toggler--default" href="#" hreflang="fr" lang="fr">
 						<abbr class="ontario-show-for-small-only" title="Français">
 							FR
 						</abbr>
@@ -36,7 +39,18 @@ describe('ontario-language-toggle', () => {
 		expect(page.rootInstance.size).toBe('default');
 	});
-	it('should render a default language of English if no language prop is passed', async () => {
+	/**
+	 * TODO: Determine if this is testable.
+	 *
+	 * Not sure how to properly test against this, seems to be a race condition.
+	 *
+	 * Takes a few processes before the html lang attribute is updated.
+	 *
+	 * Using setTimeout() leads to a false positive.
+	 *
+	 * Using page.waitForChanges() or autoApplyChanges: true seem to have no effect.
+	 */
+	it.skip('should render a default language of English on the <html> tag if no language prop is passed', async () => {
 		const page = await newSpecPage({
 			components: [OntarioLanguageToggle],
 			html: `<ontario-language-toggle></ontario-language-toggle>`,
@@ -54,7 +68,7 @@ describe('ontario-language-toggle', () => {
 		expect(page.root).toEqualHtml(`
 			<ontario-language-toggle size="small" url="/en" language="fr">
 				<mock:shadow-root>
-					<a aria-label="Cliquez pour changer de langue en anglais" class="ontario-language-toggler ontario-language-toggler--small" href="/en">
+					<a aria-label="Click to switch the language to English" class="ontario-language-toggler ontario-language-toggler--small" href="/en" hreflang="en" lang="en">
 						<span>
 							English
 						</span>

package/src/components.d.ts CHANGED Viewed

@@ -1725,7 +1725,10 @@ export namespace Components {
 		 * A custom function to pass to the language toggle button.  This is optional.
 		 */
 		customLanguageToggle?: (event: globalThis.Event) => void;
-		language: Language | string;
+		/**
+		 * The language of the component.  In most cases, the language toggle should be the source of truth for determining the site language.  Only pass a language value here if necessary.
+		 */
+		language?: Language;
 		/**
 		 * The size of the language toggle button.  If no prop is passed, it will be set to the `default` size.
 		 */
@@ -2893,7 +2896,7 @@ declare global {
 		new (): HTMLOntarioInputElement;
 	};
 	interface HTMLOntarioLanguageToggleElementEventMap {
-		setAppLanguage: string;
+		setAppLanguage: Language;
 		headerLanguageToggled: HeaderLanguageToggleEventDetails;
 	}
 	interface HTMLOntarioLanguageToggleElement extends Components.OntarioLanguageToggle, HTMLStencilElement {
@@ -4923,15 +4926,18 @@ declare namespace LocalJSX {
 		 * A custom function to pass to the language toggle button.  This is optional.
 		 */
 		customLanguageToggle?: (event: globalThis.Event) => void;
-		language?: Language | string;
 		/**
-		 * An event that emits to other components that the language toggle button has been toggled.
+		 * The language of the component.  In most cases, the language toggle should be the source of truth for determining the site language.  Only pass a language value here if necessary.
+		 */
+		language?: Language;
+		/**
+		 * Event that fires when the language toggle is pressed/clicked.  The event contains the oldLanguage along with the newLanguage.
 		 */
 		onHeaderLanguageToggled?: (event: OntarioLanguageToggleCustomEvent<HeaderLanguageToggleEventDetails>) => void;
 		/**
-		 * An event to set the Document's HTML lang property, and emit the toggled language to other components.
+		 * Event that fires during the setAppLanguageHandler() method.  The event contains the current language (after language logic has already occurred).
 		 */
-		onSetAppLanguage?: (event: OntarioLanguageToggleCustomEvent<string>) => void;
+		onSetAppLanguage?: (event: OntarioLanguageToggleCustomEvent<Language>) => void;
 		/**
 		 * The size of the language toggle button.  If no prop is passed, it will be set to the `default` size.
 		 */

package/src/french.html ADDED Viewed

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html dir="ltr" lang="fr">
+	<head>
+		<link rel="stylesheet" href="/build/ontario-design-system-components.css" />
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+		<title>Ontario Design System - component samples</title>
+		<script type="module" src="/build/ontario-design-system-components.esm.js"></script>
+		<script nomodule src="/build/ontario-design-system-components.js"></script>
+	</head>
+	<body>
+		<ontario-header
+			id="ontarioHeader"
+			type="serviceOntario"
+			application-header-info='{
+				"title": "Application name",
+				"href": "/application-homepage",
+				"maxSubheaderDesktopLinks": "3",
+				"maxSubheaderTabletLinks": "2",
+				"maxSubheaderMobileLinks": "1"
+			}'
+			language-toggle-options='{
+				"englishLink": "/index.html",
+				"frenchLink" : "/french.html"
+			}'
+		>
+		</ontario-header>
+		<script>
+			function activateHeaderType(headerType) {
+				const ontarioHeaderElement = document.querySelector('ontario-header');
+				ontarioHeaderElement.type = headerType;
+			}
+		</script>
+	</body>
+</html>

package/src/index.html CHANGED Viewed

@@ -14,6 +14,7 @@
 			<a href="https://designsystem.ontario.ca/">Ontario Design System</a> web components now available!!!
 		</ontario-critical-alert>
 		<ontario-header
+			id="ontarioHeader"
 			type="serviceOntario"
 			application-header-info='{
 				"title": "Application name",
@@ -22,6 +23,10 @@
 				"maxSubheaderTabletLinks": "2",
 				"maxSubheaderMobileLinks": "1"
 			}'
+			language-toggle-options='{
+				"englishLink": "/",
+				"frenchLink" : "/french.html"
+			}'
 		>
 		</ontario-header>
@@ -1203,6 +1208,20 @@
 		<ontario-back-to-top />
 		<script>
+			const changeLanguage = (e) => {
+				e.preventDefault();
+				let header = document.getElementById('ontarioHeader');
+				header.customLanguageToggle = () => {
+					setTimeout(() => {
+						window.location.href = '/french.html';
+						console.log(header);
+						console.log('Lang switch');
+					}, 5000);
+				};
+			};
+			window.addEventListener('load', changeLanguage);
 			function testFunction() {
 				alert('HELLO WORLD!');
 			}