@brightspace-ui/core 2.101.3 → 2.103.0

package/helpers/localize-core-element.js

@@ -1,6 +1,6 @@
-import { LocalizeDynamicMixin } from '../mixins/localize-dynamic-mixin.js';
+import { LocalizeMixin } from '../mixins/localize/localize-mixin.js';
 
-export const LocalizeCoreElement = superclass => class extends LocalizeDynamicMixin(superclass) {
+export const LocalizeCoreElement = superclass => class extends LocalizeMixin(superclass) {
 
 	static get localizeConfig() {
 		return {

package/mixins/{localize-mixin.md → localize/README.md}

@@ -1,6 +1,6 @@
 # Localization Mixins
 
-The `LocalizeDynamicMixin` and `LocalizeStaticMixin` allow you to localize text in your components and have it displayed to the user in their preferred language.
+The `LocalizeMixin` and `LocalizeStaticMixin` allow you to localize text in your components and have it displayed to the user in their preferred language.
 
 ## Providing Resources
 
@@ -27,14 +27,14 @@ Always provide language resources for base languages (e.g. `en`, `fr`, `pt`, etc
 
 ### Static vs. Dynamic Resources
 
-For components with local resources, use the `LocalizeStaticMixin` and implement a `static` `resources` getter that returns the local resources synchronously. To get resources asynchronously, use the `LocalizeDynamicMixin` and implement a `static` `localizeConfig` getter that returns details about where to find your resources.
+For components with local resources, use the `LocalizeStaticMixin` and implement a `static` `resources` getter that returns the local resources synchronously. To get resources asynchronously, use the `LocalizeMixin` and implement a `static` `localizeConfig` getter that returns details about where to find your resources.
 
 #### Example 1: Static Resources
 
 If your component has a small number of translations, it may make sense to store them locally within the component in a constant.
 
 ```javascript
-import { LocalizeStaticMixin } from '@brightspace-ui/core/mixins/localize-static-mixin.js';
+import { LocalizeStaticMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
 
 class MyComponent extends LocalizeStaticMixin(LitElement) {
 
@@ -68,9 +68,9 @@ export default {
 
 Then create your `localizeConfig` getter:
 ```javascript
-import { LocalizeDynamicMixin } from '@brightspace-ui/core/mixins/localize-dynamic-mixin.js';
+import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
 
-class MyComponent extends LocalizeDynamicMixin(LitElement) {
+class MyComponent extends LocalizeMixin(LitElement) {
 
   static get localizeConfig() {
     return {
@@ -102,13 +102,13 @@ static get localizeConfig() {
 }
 ```
 
-**Note:** If using `LocalizeCoreElement` or a mixin that utilizes `LocalizeCoreElement` as well as `LocalizeDynamicMixin` or a mixin that uses `LocalizeDynamicMixin`, `LocalizeDynamicMixin` **must** appear before `LocalizeCoreElement` in the chain. For example:
+**Note:** If using `LocalizeCoreElement` or a mixin that utilizes `LocalizeCoreElement` as well as `LocalizeMixin` or a mixin that uses `LocalizeMixin`, `LocalizeMixin` **must** appear before `LocalizeCoreElement` in the chain. For example:
 
 ```javascript
 import { LocalizeCoreElement } from '@brightspace-ui/core/helpers/localize-core-element.js';
-import { LocalizeDynamicMixin } from '@brightspace-ui/core/mixins/localize-dynamic-mixin.js';
+import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
 
-class MyComponent extends LocalizeDynamicMixin(LocalizeCoreElement(LitElement)) {
+class MyComponent extends LocalizeMixin(LocalizeCoreElement(LitElement)) {
   ...
 }
 ```
@@ -121,6 +121,66 @@ If your localized string contains arguments, pass them as a key-value object as
 
 ```javascript
 render() {
-  return html`<p>${this.localize('hello', {firstName: 'Mary'})}</p>`;
+  return html`<p>${this.localize('hello', { firstName: 'Mary' })}</p>`;
 }
 ```
+
+## `localizeHTML()`
+
+Rich formatting can be included in localization resources and safely converted to HTML with the `localizeHTML()` method.
+
+### Basic Formatting
+
+The following formatting elements are supported out-of-the-box:
+
+* `<p>paragraphs</p>`
+* `line<br></br>breaks` (note the end tag is required)
+* `<b>bold</b>`
+* `<strong>strong</strong>`
+* `<i>italic</i>`
+* `<em>emphasis</em>`
+
+Remember that `<strong>` is for content of greater importance (browsers show this visually using bold), while `<b>` only bolds the text visually without increasing its importance.
+
+Similarly `<em>` *emphasizes* a particular piece of text (browsers show this visually using italics), whereas `<i>` only italicizes the text visually without emphasis.
+
+### Links
+
+To wrap text in [a link](../../components/link/), define a unique tag in the localization resource:
+
+```json
+{
+  "myTerm": "Create a <linkNew>new assignment</linkNew>."
+}
+```
+
+Then import the `generateLink` helper and use it to provide the `href` and optional `target` as replacements:
+
+```javascript
+import { generateLink } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
+
+this.localizeHTML('myTerm', {
+  linkNew: generateLink({ href: 'new.html', target: '_blank' })
+});
+```
+
+### Help Tooltips
+
+To use a [help tooltip](../../components/tooltip/), define a unique tag in the localization resource in addition to the tooltip's text:
+
+```json
+{
+  "octopus": "An octopus is a member of the <tooltip>cephalopod</tooltip> family.",
+  "cephalopodTooltip": "Cephalopods are members of the molluscan class Cephalopoda"
+}
+```
+
+Then import `generateTooltipHelp` and pass it the tooltip term value:
+
+```javascript
+import { generateTooltipHelp } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
+
+this.localizeHTML('octopus', {
+  tooltip: generateTooltipHelp({ contents: this.localize('cephalopodTooltip') })
+});
+```

package/mixins/localize/demo/localize-mixin-greeting.js

@@ -0,0 +1,39 @@
+import { html, LitElement } from 'lit';
+import { LocalizeMixin } from '../localize-mixin.js';
+
+class Greeting extends LocalizeMixin(LitElement) {
+
+	static get properties() {
+		return {
+			name: {	type: String }
+		};
+	}
+
+	static get localizeConfig() {
+		const langResources = {
+			'ar': { 'hello': 'مرحبا {name}' },
+			'de': { 'hello': 'Hallo {name}' },
+			'en': { 'hello': 'Hello, {name}' },
+			'en-gb': { 'hello': '\'Ello, {name}' },
+			'es': { 'hello': 'Hola {name}' },
+			'fr': { 'hello': 'Bonjour, {name}' },
+			'ja': { 'hello': 'こんにちは {name}' },
+			'ko': { 'hello': '안녕하세요 {name}' },
+			'pt-br': { 'hello': 'Olá {name}' },
+			'tr': { 'hello': 'Merhaba {name}' },
+			'zh-cn': { 'hello': '你好 {name}' },
+			'zh-tw': { 'hello': '你好 {name}' }
+		};
+		return {
+			importFunc: async lang => langResources[lang]
+		};
+	}
+
+	render() {
+		return html`
+			<p>${this.localize('hello', { name: this.name })}</p>
+		`;
+	}
+}
+
+customElements.define('d2l-greeting', Greeting);

package/mixins/localize/demo/localize-mixin-mission.js

@@ -0,0 +1,29 @@
+import { generateLink, localizeMarkup, LocalizeMixin } from '../localize-mixin.js';
+import { LitElement } from 'lit';
+
+class Mission extends LocalizeMixin(LitElement) {
+
+	static get localizeConfig() {
+		const langResources = {
+			'en': { mission: '<p><link1>Transforming</link1> the way</p><link2> <b>{name}</b></link2> learns. \'<div></div>\'' },
+			'fr': { mission: '<p><link1>Transformer</link1> la façon dont</p><link2> <br></br> <b>{name}</b></link2> apprend' }
+		};
+		return {
+			importFunc: async lang => langResources[lang]
+		};
+	}
+
+	render() {
+		const surname = 'Smith';
+		const surnameMarkup = localizeMarkup`<i>${surname}</i>`;
+		const replacements = {
+			name: 'Bill',
+			link1: generateLink({ href: 'https://wikipedia.org/wiki/Culture_change', target: '_blank' }),
+			link2: chunks => localizeMarkup`<d2l-link href="https://wikipedia.org/wiki/Earth" target="_blank"><em>${chunks}</em> ${surnameMarkup}</d2l-link>`
+		};
+
+		return this.localizeHTML('mission', replacements);
+	}
+}
+
+customElements.define('d2l-mission', Mission);

package/mixins/localize/demo/localize-mixin.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<meta charset="UTF-8">
+		<link rel="stylesheet" href="../../../components/demo/styles.css" type="text/css">
+		<script type="module">
+			import '../../../components/demo/demo-page.js';
+			import './localize-mixin-greeting.js';
+			import './localize-mixin-mission.js';
+		</script>
+	</head>
+	<body unresolved>
+		<d2l-demo-page page-title="localize-mixin">
+
+			<h2>localize()</h2>
+			<d2l-demo-snippet>
+				<d2l-greeting name="Bill"></d2l-greeting>
+			</d2l-demo-snippet>
+
+			<h2>localizeHTML()</h2>
+			<d2l-demo-snippet>
+				<d2l-mission></d2l-mission>
+			</d2l-demo-snippet>
+
+		</d2l-demo-page>
+	</body>
+</html>

package/mixins/localize/localize-mixin.js

@@ -0,0 +1,288 @@
+import '@formatjs/intl-pluralrules/dist-es6/polyfill-locales.js';
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { getDocumentLocaleSettings } from '@brightspace-ui/intl/lib/common.js';
+import { getLocalizeOverrideResources } from '../../helpers/getLocalizeResources.js';
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import IntlMessageFormat from 'intl-messageformat';
+
+const fallbackLang = 'en';
+const supportedLangpacks = ['ar', 'cy', 'da', 'de', 'en', 'en-gb', 'es', 'es-es', 'fr', 'fr-fr', 'fr-on', 'hi', 'ja', 'ko', 'nl', 'pt', 'sv', 'tr', 'zh-cn', 'zh-tw'];
+
+export const _LocalizeMixinBase = dedupeMixin(superclass => class LocalizeMixinClass extends superclass {
+
+	static get properties() {
+		return {
+			__resources: { type: Object, attribute: false  }
+		};
+	}
+
+	static documentLocaleSettings = getDocumentLocaleSettings();
+
+	constructor() {
+		super();
+		this.__resourcesLoadedPromise = new Promise((resolve) => {
+			let first = true;
+			this.__languageChangeCallback = () => {
+				if (!this._hasResources()) return;
+				const localizeResources = this.constructor._getAllLocalizeResources();
+				const resourcesLoadedPromise = Promise.all(localizeResources);
+				resourcesLoadedPromise
+					.then((results) => {
+						if (results.length === 0) {
+							return;
+						}
+						const resources = {};
+						for (const res of results) {
+							const language = res.language;
+							for (const [key, value] of Object.entries(res.resources)) {
+								resources[key] = { language, value };
+							}
+						}
+						this.__resources = resources;
+						this._onResourcesChange();
+						if (first) {
+							resolve();
+							first = false;
+						}
+					});
+			};
+		});
+
+		this.__updatedProperties = new Map();
+	}
+
+	connectedCallback() {
+		super.connectedCallback();
+		this.constructor.documentLocaleSettings.addChangeListener(this.__languageChangeCallback);
+		this.__languageChangeCallback();
+	}
+
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		this.constructor.documentLocaleSettings.removeChangeListener(this.__languageChangeCallback);
+		this.__updatedProperties.clear();
+	}
+
+	shouldUpdate(changedProperties) {
+
+		const hasResources = this._hasResources();
+		if (!hasResources) {
+			return super.shouldUpdate(changedProperties);
+		}
+
+		const ready = this.__resources !== undefined;
+		if (!ready) {
+			changedProperties.forEach((oldValue, propName) => {
+				this.__updatedProperties.set(propName, oldValue);
+			});
+			return false;
+		}
+
+		this.__updatedProperties.forEach((oldValue, propName) => {
+			if (!changedProperties.has(propName)) {
+				changedProperties.set(propName, oldValue);
+			}
+		});
+		this.__updatedProperties.clear();
+
+		return super.shouldUpdate(changedProperties);
+
+	}
+
+	async getUpdateComplete() {
+		await super.getUpdateComplete();
+		const hasResources = this._hasResources();
+		const resourcesLoaded = this.__resources !== undefined;
+		if (!hasResources || resourcesLoaded) {
+			return;
+		}
+		await this.__resourcesLoadedPromise;
+	}
+
+	localize(key) {
+
+		const { language, value } = this.__resources?.[key] ?? {};
+		if (!value) return '';
+
+		let params = {};
+		if (arguments.length > 1 && arguments[1].constructor === Object) {
+			// support for key-value replacements as a single arg
+			params = arguments[1];
+		} else {
+			// legacy support for localize-behavior replacements as many args
+			for (let i = 1; i < arguments.length; i += 2) {
+				params[arguments[i]] = arguments[i + 1];
+			}
+		}
+
+		const translatedMessage = new IntlMessageFormat(value, language);
+		let formattedMessage = value;
+		try {
+			if (Object.values(params).some(v => typeof v === 'function')) throw 'localize() does not support rich text.';
+			formattedMessage = translatedMessage.format(params);
+		} catch (e) {
+			console.error(e);
+		}
+
+		return formattedMessage;
+	}
+
+	localizeHTML(key, params = {}) {
+
+		const { language, value } = this.__resources?.[key] ?? {};
+		if (!value) return '';
+
+		const translatedMessage = new IntlMessageFormat(value, language);
+		let formattedMessage = value;
+		try {
+			formattedMessage = translatedMessage.format({
+				b: chunks => localizeMarkup`<b>${chunks}</b>`,
+				br: () => localizeMarkup`<br>`,
+				em: chunks => localizeMarkup`<em>${chunks}</em>`,
+				i: chunks => localizeMarkup`<i>${chunks}</i>`,
+				p: chunks => localizeMarkup`<p>${chunks}</p>`,
+				strong: chunks => localizeMarkup`<strong>${chunks}</strong>`,
+				...params
+			});
+			validateMarkup(formattedMessage);
+		} catch (e) {
+			console.error(e);
+		}
+
+		return formattedMessage;
+	}
+
+	static _generatePossibleLanguages(config) {
+
+		if (config?.useBrowserLangs) return navigator.languages.map(e => e.toLowerCase()).concat('en');
+
+		const { language, fallbackLanguage } = this.documentLocaleSettings;
+		const langs = [ language, fallbackLanguage ]
+			.filter(e => e)
+			.map(e => [ e.toLowerCase(), e.split('-')[0] ])
+			.flat();
+
+		return Array.from(new Set([ ...langs, 'en-us', 'en' ]));
+	}
+
+	static _getAllLocalizeResources(config = this.localizeConfig) {
+		let resourcesLoadedPromises = [];
+		const superCtor = Object.getPrototypeOf(this);
+		// get imported terms for each config, head up the chain to get them all
+		if ('_getAllLocalizeResources' in superCtor) {
+			const superConfig = Object.prototype.hasOwnProperty.call(superCtor, 'localizeConfig') && superCtor.localizeConfig.importFunc ? superCtor.localizeConfig : config;
+			resourcesLoadedPromises = superCtor._getAllLocalizeResources(superConfig);
+		}
+		if (Object.prototype.hasOwnProperty.call(this, 'getLocalizeResources') || Object.prototype.hasOwnProperty.call(this, 'resources')) {
+			const possibleLanguages = this._generatePossibleLanguages(config);
+			const res = this.getLocalizeResources(possibleLanguages, config);
+			resourcesLoadedPromises.push(res);
+		}
+		return resourcesLoadedPromises;
+	}
+
+	_hasResources() {
+		return this.constructor['getLocalizeResources'] !== undefined;
+	}
+
+	_onResourcesChange() {
+		/** @ignore */
+		this.dispatchEvent(new CustomEvent('d2l-localize-resources-change'));
+	}
+
+});
+
+export const LocalizeMixin = superclass => class extends _LocalizeMixinBase(superclass) {
+
+	static async getLocalizeResources(langs, { importFunc, osloCollection, useBrowserLangs }) {
+
+		// in dev, don't request unsupported langpacks
+		if (!importFunc.toString().includes('switch') && !useBrowserLangs) {
+			langs = langs.filter(lang => supportedLangpacks.includes(lang));
+		}
+
+		for (const lang of [...langs, fallbackLang]) {
+
+			const resources = await Promise.resolve(importFunc(lang)).catch(() => {});
+
+			if (resources) {
+
+				if (osloCollection) {
+					return await getLocalizeOverrideResources(
+						lang,
+						resources,
+						() => osloCollection
+					);
+				}
+
+				return {
+					language: lang,
+					resources
+				};
+			}
+		}
+	}
+
+	static get localizeConfig() {
+		return {};
+	}
+
+};
+
+export const LocalizeStaticMixin = superclass => class extends _LocalizeMixinBase(superclass) {
+
+	static async getLocalizeResources(langs) {
+		let resolvedLang = fallbackLang;
+		const resolvedResources = Object.assign({}, this.resources[fallbackLang]);
+
+		langs.reverse().forEach((lang) => {
+			if (this.resources[lang]) {
+				resolvedLang = lang;
+				Object.assign(resolvedResources, this.resources[lang]);
+			}
+		});
+
+		return {
+			language: resolvedLang,
+			resources: resolvedResources
+		};
+	}
+
+	static get resources() {
+		return { 'en': {} };
+	}
+
+};
+
+export const allowedTags = Object.freeze(['d2l-link', 'd2l-tooltip-help', 'p', 'br', 'b', 'strong', 'i', 'em']);
+
+const markupError = `localizeHTML() rich-text replacements must use localizeMarkup templates with only the following allowed elements: ${allowedTags}. For more information, see: https://github.com/BrightspaceUI/core/blob/main/mixins/localize/`;
+const validTerminators = '([>\\s/]|$)';
+const allowedAfterTriangleBracket = `/?(${allowedTags.join('|')})?${validTerminators}`;
+const disallowedTagsRegex = new RegExp(`<(?!${allowedAfterTriangleBracket})`);
+
+function validateMarkup(content, applyRegex) {
+	if (content) {
+		if (content.map) return content.forEach(item => validateMarkup(item));
+		if (content._localizeMarkup) return;
+		if (Object.hasOwn(content, '_$litType$')) throw markupError;
+		if (applyRegex && content.constructor === String && disallowedTagsRegex.test(content)) throw markupError;
+	}
+}
+
+export function localizeMarkup(strings, ...expressions) {
+	strings.forEach(str => validateMarkup(str, true));
+	expressions.forEach(exp => validateMarkup(exp, true));
+	return { ...html(strings, ...expressions), _localizeMarkup: true };
+}
+
+export function generateLink({ href, target }) {
+	import('../../components/link/link.js');
+	return chunks => localizeMarkup`<d2l-link href="${ifDefined(href)}" target="${ifDefined(target)}">${chunks}</d2l-link>`;
+}
+
+export function generateTooltipHelp({ contents }) {
+	import('../../components/tooltip/tooltip-help.js');
+	return chunks => localizeMarkup`<d2l-tooltip-help inherit-font-style text="${ifDefined(chunks)}">${contents}</d2l-tooltip-help>`;
+}

package/mixins/localize-dynamic-mixin.js

@@ -1,42 +1 @@
-import { getLocalizeOverrideResources } from '../helpers/getLocalizeResources.js';
-import { LocalizeMixin } from './localize-mixin.js';
-
-const fallbackLang = 'en';
-const supportedLangpacks = ['ar', 'cy', 'da', 'de', 'en', 'en-gb', 'es', 'es-es', 'fr', 'fr-fr', 'fr-on', 'hi', 'ja', 'ko', 'nl', 'pt', 'sv', 'tr', 'zh-cn', 'zh-tw'];
-
-export const LocalizeDynamicMixin = superclass => class extends LocalizeMixin(superclass) {
-
-	static async getLocalizeResources(langs, { importFunc, osloCollection, useBrowserLangs }) {
-
-		// in dev, don't request unsupported langpacks
-		if (!importFunc.toString().includes('switch') && !useBrowserLangs) {
-			langs = langs.filter(lang => supportedLangpacks.includes(lang));
-		}
-
-		for (const lang of [...langs, fallbackLang]) {
-
-			const resources = await importFunc(lang).catch(() => {});
-
-			if (resources) {
-
-				if (osloCollection) {
-					return await getLocalizeOverrideResources(
-						lang,
-						resources,
-						() => osloCollection
-					);
-				}
-
-				return {
-					language: lang,
-					resources
-				};
-			}
-		}
-	}
-
-	static get localizeConfig() {
-		return {};
-	}
-
-};
+export { LocalizeMixin as LocalizeDynamicMixin } from './localize/localize-mixin.js';