@ui5/webcomponents-base 0.0.0-d0bcf47c7 → 0.0.0-d4d43327a

package/src/features/OpenUI5Support.ts

@@ -0,0 +1,153 @@
+import { registerFeature } from "../FeaturesRegistry.js";
+import { setTheme } from "../config/Theme.js";
+import { getCurrentZIndex } from "../util/PopupUtils.js";
+import { CLDRData } from "../asset-registries/LocaleData.js";
+import type { LegacyDateCalendarCustomizing } from "../features/LegacyDateFormats.js";
+
+type OpenUI5Popup = {
+	setInitialZIndex: (zIndex: number) => void,
+	getNextZIndex: () => number,
+};
+
+type OpenUI5Core = {
+	attachInit: (callback: () => void) => void,
+	attachThemeChanged: (callback: () => Promise<void>) => void,
+	getConfiguration: () => OpenUI5CoreConfiguration,
+};
+
+type OpenUI5CoreConfiguration = {
+	getAnimationMode: () => string,
+	getLanguage: () => string,
+	getTheme: () => string,
+	getThemeRoot: () => string,
+	getRTL: () => string,
+	getCalendarType: () => string,
+	getLocale: () => string,
+	getFormatSettings: () => {
+		getLegacyDateCalendarCustomizing: () => LegacyDateCalendarCustomizing;
+	}
+};
+
+type LocaleData = {
+	getInstance: (locale: string) => Locale,
+}
+
+type Locale = {
+	getFirstDayOfWeek: () => number,
+	_get: () => CLDRData,
+};
+
+const getCore = () => {
+	return window.sap?.ui?.getCore?.() as OpenUI5Core;
+};
+
+class OpenUI5Support {
+	static isLoaded() {
+		return !!getCore();
+	}
+
+	static init() {
+		const core = getCore();
+		if (!core) {
+			return Promise.resolve();
+		}
+
+		return new Promise<void>(resolve => {
+			core.attachInit(() => {
+				window.sap.ui.require(["sap/ui/core/LocaleData", "sap/ui/core/Popup"], (LocaleData: LocaleData, Popup: OpenUI5Popup) => {
+					Popup.setInitialZIndex(getCurrentZIndex());
+					resolve();
+				});
+			});
+		});
+	}
+
+	static getConfigurationSettingsObject() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		const config = core.getConfiguration();
+		const LocaleData = window.sap.ui.require("sap/ui/core/LocaleData");
+
+		return {
+			animationMode: config.getAnimationMode(),
+			language: config.getLanguage(),
+			theme: config.getTheme(),
+			themeRoot: config.getThemeRoot(),
+			rtl: config.getRTL(),
+			calendarType: config.getCalendarType(),
+			formatSettings: {
+				firstDayOfWeek: LocaleData ? LocaleData.getInstance(config.getLocale()).getFirstDayOfWeek() : undefined,
+				legacyDateCalendarCustomizing: config.getFormatSettings().getLegacyDateCalendarCustomizing(),
+			},
+		};
+	}
+
+	static getLocaleDataObject() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		const config = core.getConfiguration();
+		const LocaleData = window.sap.ui.require("sap/ui/core/LocaleData") as LocaleData;
+		return LocaleData.getInstance(config.getLocale())._get();
+	}
+
+	static _listenForThemeChange() {
+		const core = getCore();
+		const config = core.getConfiguration();
+		core.attachThemeChanged(async () => {
+			await setTheme(config.getTheme());
+		});
+	}
+
+	static attachListeners() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		OpenUI5Support._listenForThemeChange();
+	}
+
+	static cssVariablesLoaded() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		const link = [...document.head.children].find(el => el.id === "sap-ui-theme-sap.ui.core") as HTMLLinkElement; // more reliable than querySelector early
+		if (!link) {
+			return;
+		}
+
+		return !!link.href.match(/\/css(-|_)variables\.css/);
+	}
+
+	static getNextZIndex() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		const Popup = window.sap.ui.require("sap/ui/core/Popup") as OpenUI5Popup;
+		return Popup.getNextZIndex();
+	}
+
+	static setInitialZIndex() {
+		const core = getCore();
+		if (!core) {
+			return;
+		}
+
+		const Popup = window.sap.ui.require("sap/ui/core/Popup") as OpenUI5Popup;
+		Popup.setInitialZIndex(getCurrentZIndex());
+	}
+}
+
+registerFeature("OpenUI5Support", OpenUI5Support);
+
+export default OpenUI5Support;

package/src/generated/css/BusyIndicator.css.ts

@@ -0,0 +1,9 @@
+import type { StyleData } from "../../types.js";
+
+const styleData: StyleData = {
+	packageName: "@ui5/webcomponents-base",
+	fileName: "BusyIndicator.css",
+	content: `.busy-indicator-wrapper{position:relative;height:100%;width:100%}.busy-indicator-overlay{display:var(--ui5_web_components_busy_indicator_display);position:absolute;inset:0;background:var(--ui5_web_components_busy_indicator_background-color);z-index:99}.busy-indicator-busy-area{display:var(--ui5_web_components_busy_indicator_display);position:absolute;z-index:99;inset:0;justify-content:center;align-items:center;background-color:inherit;flex-direction:column;color:var(--_ui5_busy_indicator_color)}:host([__is-busy]) .busy-indicator-wrapper>:not(.busy-indicator-busy-area):not(.busy-indicator-overlay):not([busy-indicator-before-span]){--ui5_web_components_busy_indicator_display:none}.busy-indicator-busy-area:focus{outline:var(--_ui5_busy_indicator_focus_outline);outline-offset:-.125rem}.busy-indicator-circle{width:1rem;height:1rem;display:inline-block;background-color:currentColor;border-radius:50%}.circle-animation-0{animation:grow 1.6s infinite cubic-bezier(.32,.06,.85,1.11)}.circle-animation-1{animation:grow 1.6s infinite cubic-bezier(.32,.06,.85,1.11);animation-delay:.2s}.circle-animation-2{animation:grow 1.6s infinite cubic-bezier(.32,.06,.85,1.11);animation-delay:.4s}.sapUiLocalBusy{--ui5_web_components_busy_indicator_display:none}.busy-indicator-wrapper [ui5-busy-indicator]{display:none}@keyframes grow{0%,100%,50%{-webkit-transform:scale(.5);-moz-transform:scale(.5);-ms-transform:scale(.5);transform:scale(.5)}25%{-webkit-transform:scale(1);-moz-transform:scale(1);-ms-transform:scale(1);transform:scale(1)}}`,
+};
+
+export default styleData;

package/src/generated/css/FontFace.css.ts

@@ -0,0 +1,9 @@
+import type { StyleData } from "../../types.js";
+
+const styleData: StyleData = {
+	packageName: "@ui5/webcomponents-base",
+	fileName: "FontFace.css",
+	content: `@font-face{font-family:"72";font-style:normal;font-weight:400;src:local("72"),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Regular.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:"72full";font-style:normal;font-weight:400;src:local('72-full'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Regular-full.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:"72";font-style:normal;font-weight:700;src:local('72-Bold'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Bold.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:"72full";font-style:normal;font-weight:700;src:local('72-Bold-full'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Bold-full.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:'72-Bold';font-style:normal;src:local('72-Bold'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Bold.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:'72-Boldfull';font-style:normal;src:url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Bold-full.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:'72-Light';font-style:normal;src:local('72-Light'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Light.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:'72-Lightfull';font-style:normal;src:url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_fiori_3/fonts/72-Light-full.woff2?ui5-webcomponents) format("woff2")}@font-face{font-family:"72Black";font-style:bold;font-weight:900;src:local('72Black'),url(https://sdk.openui5.org/resources/sap/ui/core/themes/sap_horizon/fonts/72-Black.woff2?ui5-webcomponents) format("woff2")}`,
+};
+
+export default styleData;

package/src/generated/css/OverrideFontFace.css.ts

@@ -0,0 +1,9 @@
+import type { StyleData } from "../../types.js";
+
+const styleData: StyleData = {
+	packageName: "@ui5/webcomponents-base",
+	fileName: "OverrideFontFace.css",
+	content: `@font-face{font-family:'72override';unicode-range:U+0102-0103,U+01A0-01A1,U+01AF-01B0,U+1EA0-1EB7,U+1EB8-1EC7,U+1EC8-1ECB,U+1ECC-1EE3,U+1EE4-1EF1,U+1EF4-1EF7;src:local('Arial'),local('Helvetica'),local('sans-serif')}`,
+};
+
+export default styleData;

package/src/generated/css/SystemCSSVars.css.ts

@@ -0,0 +1,9 @@
+import type { StyleData } from "../../types.js";
+
+const styleData: StyleData = {
+	packageName: "@ui5/webcomponents-base",
+	fileName: "SystemCSSVars.css",
+	content: `:root{--_ui5_content_density:cozy}.sapUiSizeCompact,.ui5-content-density-compact,[data-ui5-compact-size]{--_ui5_content_density:compact}[dir=rtl]{--_ui5_dir:rtl}[dir=ltr]{--_ui5_dir:ltr}`,
+};
+
+export default styleData;

package/src/getSharedResource.ts

@@ -0,0 +1,39 @@
+import getSingletonElementInstance from "./util/getSingletonElementInstance.js";
+
+const getSharedResourcesInstance = (): Record<string, unknown> | null => {
+	if (typeof document === "undefined") {
+		return null;
+	}
+	return getSingletonElementInstance("ui5-shared-resources", document.head) as unknown as Record<string, unknown>;
+};
+
+/**
+ * Use this method to initialize/get resources that you would like to be shared among UI5 Web Components runtime instances.
+ * The data will be accessed via a singleton "ui5-shared-resources" HTML element in the "head" element of the page.
+ *
+ * @public
+ * @param namespace Unique ID of the resource, may contain "." to denote hierarchy
+ * @param initialValue Object or primitive that will be used as an initial value if the resource does not exist
+ * @returns {*}
+ */
+const getSharedResource = <T>(namespace: string, initialValue: T): T => {
+	const parts = namespace.split(".");
+	let current = getSharedResourcesInstance() as Record<string, any>;
+
+	if (!current) {
+		return initialValue;
+	}
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		const lastPart = i === parts.length - 1;
+		if (!Object.prototype.hasOwnProperty.call(current, part)) {
+			current[part] = lastPart ? initialValue : {};
+		}
+		current = current[part];
+	}
+
+	return current as T;
+};
+
+export default getSharedResource;

package/src/global.d.ts

@@ -0,0 +1,38 @@
+export {};
+
+declare global {
+
+	type VersionInfo = {
+		version: string,
+		major: number,
+		minor: number,
+		patch: number,
+		suffix: string,
+		isNext: boolean,
+		buildTime: number,
+	}
+
+	interface Window {
+		sap: any;
+		chrome: any;
+		v8: any;
+	}
+
+	module "*generated/AssetParameters.js" {
+		const DEFAULT_THEME: string;
+		const DEFAULT_LANGUAGE: string;
+		const DEFAULT_LOCALE: string;
+		const SUPPORTED_LOCALES: Array<string>;
+		export {
+			DEFAULT_THEME,
+			DEFAULT_LANGUAGE,
+			DEFAULT_LOCALE,
+			SUPPORTED_LOCALES,
+		};
+	}
+
+	module "*generated/VersionInfo.js" {
+		const content: VersionInfo;
+		export default content;
+	}
+}

package/src/i18nBundle.ts

@@ -0,0 +1,108 @@
+import { registerI18nLoader, fetchI18nBundle, getI18nBundleData } from "./asset-registries/i18n.js";
+import formatMessage from "./util/formatMessage.js";
+
+const I18nBundleInstances = new Map<string, I18nBundle>();
+
+let customGetI18nBundle: I18nBundleGetter;
+
+type I18nText = {
+	key: string,
+	defaultText: string,
+};
+
+type I18nBundleGetter = (packageName: string) => Promise<I18nBundle>;
+
+/**
+ * @class
+ * @public
+ */
+class I18nBundle {
+	packageName: string;
+
+	constructor(packageName: string) {
+		this.packageName = packageName;
+	}
+
+	/**
+	 * Returns a text in the currently loaded language
+	 *
+	 * @public
+	 * @param {Object|String} textObj key/defaultText pair or just the key
+	 * @param params Values for the placeholders
+	 * @returns {string}
+	 */
+	getText(textObj: I18nText, ...params: Array<number | string>): string {
+		if (typeof textObj === "string") {
+			textObj = { key: textObj, defaultText: textObj };
+		}
+
+		if (!textObj || !textObj.key) {
+			return "";
+		}
+
+		const bundle = getI18nBundleData(this.packageName);
+		if (bundle && !bundle[textObj.key]) {
+			console.warn(`Key ${textObj.key} not found in the i18n bundle, the default text will be used`); // eslint-disable-line
+		}
+		const messageText = bundle && bundle[textObj.key] ? bundle[textObj.key] : (textObj.defaultText || textObj.key);
+
+		return formatMessage(messageText, params);
+	}
+}
+
+/**
+ * Returns the I18nBundle instance for the given package synchronously.
+ *
+ * @public
+ * @param packageName
+ * @returns { I18nBundle }
+ */
+const getI18nBundleSync = (packageName: string): I18nBundle => {
+	if (I18nBundleInstances.has(packageName)) {
+		return I18nBundleInstances.get(packageName)!;
+	}
+
+	const i18nBundle = new I18nBundle(packageName);
+	I18nBundleInstances.set(packageName, i18nBundle);
+	return i18nBundle;
+};
+
+/**
+ * Fetches and returns the I18nBundle instance for the given package.
+ *
+ * @public
+ * @param packageName
+ * @returns { Promise<I18nBundle> }
+ */
+const getI18nBundle = async (packageName: string): Promise<I18nBundle> => {
+	if (customGetI18nBundle) {
+		return customGetI18nBundle(packageName);
+	}
+
+	await fetchI18nBundle(packageName);
+	return getI18nBundleSync(packageName);
+};
+
+/**
+ * Allows developers to provide a custom getI18nBundle implementation
+ * If this function is called, the custom implementation will be used for all components and will completely
+ * replace the default implementation.
+ *
+ * @public
+ * @param customGet the function to use instead of the standard getI18nBundle implementation
+ */
+const registerCustomI18nBundleGetter = (customGet: I18nBundleGetter) => {
+	customGetI18nBundle = customGet;
+};
+
+export default I18nBundle;
+
+export {
+	registerI18nLoader,
+	getI18nBundle,
+	registerCustomI18nBundleGetter,
+};
+
+export type {
+	I18nText,
+};

package/src/locale/Locale.ts

@@ -0,0 +1,101 @@
+import { DEFAULT_LANGUAGE } from "../generated/AssetParameters.js";
+
+const rLocale = /^((?:[A-Z]{2,3}(?:-[A-Z]{3}){0,3})|[A-Z]{4}|[A-Z]{5,8})(?:-([A-Z]{4}))?(?:-([A-Z]{2}|[0-9]{3}))?((?:-[0-9A-Z]{5,8}|-[0-9][0-9A-Z]{3})*)((?:-[0-9A-WYZ](?:-[0-9A-Z]{2,8})+)*)(?:-(X(?:-[0-9A-Z]{1,8})+))?$/i;
+
+class Locale {
+	sLocaleId: string;
+	sLanguage: string;
+	sScript: string;
+	sRegion: string;
+	sVariant: string | null;
+	sExtension: string | null;
+	sPrivateUse: string | null;
+
+	constructor(sLocaleId: string) {
+		const aResult = rLocale.exec(sLocaleId.replace(/_/g, "-"));
+		if (aResult === null) {
+			throw new Error(`The given language ${sLocaleId} does not adhere to BCP-47.`);
+		}
+		this.sLocaleId = sLocaleId;
+		this.sLanguage = aResult[1] || DEFAULT_LANGUAGE;
+		this.sScript = aResult[2] || "";
+		this.sRegion = aResult[3] || "";
+		this.sVariant = (aResult[4] && aResult[4].slice(1)) || null;
+		this.sExtension = (aResult[5] && aResult[5].slice(1)) || null;
+		this.sPrivateUse = aResult[6] || null;
+		if (this.sLanguage) {
+			this.sLanguage = this.sLanguage.toLowerCase();
+		}
+		if (this.sScript) {
+			this.sScript = this.sScript.toLowerCase().replace(/^[a-z]/, s => {
+				return s.toUpperCase();
+			});
+		}
+		if (this.sRegion) {
+			this.sRegion = this.sRegion.toUpperCase();
+		}
+	}
+
+	getLanguage() {
+		return this.sLanguage;
+	}
+
+	getScript() {
+		return this.sScript;
+	}
+
+	getRegion() {
+		return this.sRegion;
+	}
+
+	getVariant() {
+		return this.sVariant;
+	}
+
+	getVariantSubtags() {
+		return this.sVariant ? this.sVariant.split("-") : [];
+	}
+
+	getExtension() {
+		return this.sExtension;
+	}
+
+	getExtensionSubtags() {
+		return this.sExtension ? this.sExtension.slice(2).split("-") : [];
+	}
+
+	getPrivateUse() {
+		return this.sPrivateUse;
+	}
+
+	getPrivateUseSubtags() {
+		return this.sPrivateUse ? this.sPrivateUse.slice(2).split("-") : [];
+	}
+
+	hasPrivateUseSubtag(sSubtag: string) {
+		return this.getPrivateUseSubtags().indexOf(sSubtag) >= 0;
+	}
+
+	toString() {
+		const r = [this.sLanguage];
+
+		if (this.sScript) {
+			r.push(this.sScript);
+		}
+		if (this.sRegion) {
+			r.push(this.sRegion);
+		}
+		if (this.sVariant) {
+			r.push(this.sVariant);
+		}
+		if (this.sExtension) {
+			r.push(this.sExtension);
+		}
+		if (this.sPrivateUse) {
+			r.push(this.sPrivateUse);
+		}
+		return r.join("-");
+	}
+}
+
+export default Locale;

package/src/locale/RTLAwareRegistry.ts

@@ -0,0 +1,16 @@
+import type UI5Element from "../UI5Element";
+
+const rtlAwareSet = new Set<typeof UI5Element>();
+
+const markAsRtlAware = (klass: typeof UI5Element) => {
+	rtlAwareSet.add(klass);
+};
+
+const isRtlAware = (klass: typeof UI5Element) => {
+	return rtlAwareSet.has(klass);
+};
+
+export {
+	markAsRtlAware,
+	isRtlAware,
+};

package/src/locale/applyDirection.ts

@@ -0,0 +1,18 @@
+import { reRenderAllUI5Elements } from "../Render.js";
+import { fireDirectionChange } from "./directionChange.js";
+
+/**
+ * Re-renders all RTL-aware UI5 Elements.
+ *
+ * <b>Note:</b> Call this method whenever you change the "dir" property anywhere in your HTML page.
+ * <b>Example:</b> <code>document.body.dir = "rtl"; applyDirection();</code>
+ * @public
+ * @returns {Promise<void>}
+ */
+const applyDirection = async (): Promise<void> => {
+	const listenersResults = fireDirectionChange();
+	await Promise.all(listenersResults);
+	await reRenderAllUI5Elements({ rtlAware: true });
+};
+
+export default applyDirection;

package/src/locale/directionChange.ts

@@ -0,0 +1,34 @@
+import EventProvider from "../EventProvider.js";
+
+type DirectionChangeCallback = () => void;
+
+const eventProvider = new EventProvider<undefined, void>();
+const DIR_CHANGE = "directionChange";
+
+/**
+ * Attach a callback that will be executed whenever the application calls the "applyDirection" function
+ * @public
+ * @param listener
+ */
+const attachDirectionChange = (listener: DirectionChangeCallback) => {
+	eventProvider.attachEvent(DIR_CHANGE, listener);
+};
+
+/**
+ * Detach a callback that was passed with "attachDirectionChange"
+ * @public
+ * @param listener
+ */
+const detachDirectionChange = (listener: DirectionChangeCallback) => {
+	eventProvider.detachEvent(DIR_CHANGE, listener);
+};
+
+const fireDirectionChange = () => {
+	return eventProvider.fireEvent(DIR_CHANGE, undefined);
+};
+
+export {
+	attachDirectionChange,
+	detachDirectionChange,
+	fireDirectionChange,
+};

package/src/locale/getEffectiveDir.ts

@@ -0,0 +1,28 @@
+import { getRTL } from "../config/RTL.js";
+
+const GLOBAL_DIR_CSS_VAR = "--_ui5_dir";
+
+const getEffectiveDir = (element: HTMLElement) => {
+	const doc = window.document;
+	const dirValues = ["ltr", "rtl"]; // exclude "auto" and "" from all calculations
+	const locallyAppliedDir = getComputedStyle(element).getPropertyValue(GLOBAL_DIR_CSS_VAR);
+
+	// In that order, inspect the CSS Var (for modern browsers), the element itself, html and body (for IE fallback)
+	if (dirValues.includes(locallyAppliedDir)) {
+		return locallyAppliedDir;
+	}
+	if (dirValues.includes(element.dir)) {
+		return element.dir;
+	}
+	if (dirValues.includes(doc.documentElement.dir)) {
+		return doc.documentElement.dir;
+	}
+	if (dirValues.includes(doc.body.dir)) {
+		return doc.body.dir;
+	}
+
+	// Finally, check the configuration for explicitly set RTL or language-implied RTL
+	return getRTL() ? "rtl" : undefined;
+};
+
+export default getEffectiveDir;

package/src/locale/getLocale.ts

@@ -0,0 +1,46 @@
+import detectNavigatorLanguage from "../util/detectNavigatorLanguage.js";
+import { getLanguage as getConfigLanguage } from "../config/Language.js";
+import Locale from "./Locale.js";
+import { DEFAULT_LOCALE } from "../generated/AssetParameters.js";
+
+const cache = new Map<string, Locale>();
+
+const getLocaleInstance = (lang: string) => {
+	if (!cache.has(lang)) {
+		cache.set(lang, new Locale(lang));
+	}
+
+	return cache.get(lang)!;
+};
+
+const convertToLocaleOrNull = (lang: string) => {
+	try {
+		if (lang && typeof lang === "string") {
+			return getLocaleInstance(lang);
+		}
+	} catch (e) {
+		// ignore
+	}
+
+	return new Locale(DEFAULT_LOCALE);
+};
+
+/**
+ * Returns the locale based on the parameter or configured language Configuration#getLanguage
+ * If no language has been configured - a new locale based on browser language is returned
+ */
+const getLocale = (lang?: string): Locale => {
+	if (lang) {
+		return convertToLocaleOrNull(lang);
+	}
+
+	const configLanguage = getConfigLanguage();
+
+	if (configLanguage) {
+		return getLocaleInstance(configLanguage);
+	}
+
+	return convertToLocaleOrNull(detectNavigatorLanguage());
+};
+
+export default getLocale;

package/src/locale/languageChange.ts

@@ -0,0 +1,24 @@
+import EventProvider from "../EventProvider.js";
+
+type LanguageChangeCallback = (lang: string) => Promise<void | Array<void>>;
+
+const eventProvider = new EventProvider<string, Promise<void | Array<void>>>();
+const LANG_CHANGE = "languageChange";
+
+const attachLanguageChange = (listener: LanguageChangeCallback) => {
+	eventProvider.attachEvent(LANG_CHANGE, listener);
+};
+
+const detachLanguageChange = (listener: LanguageChangeCallback) => {
+	eventProvider.detachEvent(LANG_CHANGE, listener);
+};
+
+const fireLanguageChange = (lang: string) => {
+	return eventProvider.fireEventAsync(LANG_CHANGE, lang);
+};
+
+export {
+	attachLanguageChange,
+	detachLanguageChange,
+	fireLanguageChange,
+};

package/src/locale/nextFallbackLocale.ts

@@ -0,0 +1,28 @@
+import { DEFAULT_LOCALE } from "../generated/AssetParameters.js";
+
+/**
+ * Calculates the next fallback locale for the given locale.
+ *
+ * @param {string} locale Locale string in Java format (underscores) or null
+ * @returns {string} Next fallback Locale or "en" if no fallbacks found.
+ */
+const nextFallbackLocale = (locale: string) => {
+	if (!locale) {
+		return DEFAULT_LOCALE;
+	}
+
+	if (locale === "zh_HK") {
+		return "zh_TW";
+	}
+
+	// if there are multiple segments (separated by underscores), remove the last one
+	const p = locale.lastIndexOf("_");
+	if (p >= 0) {
+		return locale.slice(0, p);
+	}
+
+	// for any language but the default, fallback to the default first before falling back to the 'raw' language (empty string)
+	return locale !== DEFAULT_LOCALE ? DEFAULT_LOCALE : "";
+};
+
+export default nextFallbackLocale;