feat(framework): add ignoreUrlParams configuration option

docs/2-advanced/01-configuration.md

@@ -20,6 +20,7 @@ There are several configuration settings that affect all UI5 Web Components glob
 | [enableDefaultTooltips](#enableDefaultTooltips) | `true`, `false`                                                                                                                                                                                                                                                                                | `true`               | Whether to display default tooltips                     | Components (Icon, Button, RatingIndicator, etc.)                                                      |
 | [timezone](#timezone)                         | `Asia/Tokyo`, `Pacific/Apia`, `Asia/Kolkata`, `Europe/Sofia` and etc.                                                                                                                                                                                                                          | Your local time zone. | Allows to override your local time zone.                               | Date/time components (`ui5-date-picker`, etc.)                 |
 | [themeRoot](#themeRoot)                       | String to a URL - see the [themeRoot](#themeRoot) section below                                                                                                                                                                                                                                | N/A                   | Allows to set a URL to a Theme-designer-created custom theme.          | All components                                                 |
+| [ignoreUrlParams](#ignoreUrlParams)           | `true`, `false`                                                                                                                                                                                                                                                                                | `false`               | Whether to ignore URL parameters during configuration initialization   | Framework                                                      |
 
 ### theme
 <a name="theme"></a>
@@ -304,6 +305,26 @@ or, the preferred new format:
 
 Failing to do so will result in a warning in the console and the theme root will not be set.
 
+### ignoreUrlParams
+<a name="ignoreUrlParams"></a>
+
+*Since 2.23.0*
+
+This configuration option controls whether URL parameters (e.g. `sap-ui-theme`, `sap-ui-language`, `sap-ui-animationMode`) are processed during framework initialization.
+
+By default, the framework reads `sap-*` and `sap-ui-*` URL parameters and uses them to override the configuration script settings. While useful during development and testing, production applications may prefer to disable this behavior to ensure consistent and predictable configuration.
+
+When set to `true`, all URL parameter processing is skipped and only the configuration script and module imports are used.
+
+Example:
+```html
+<script data-ui5-config type="application/json">
+{
+	"ignoreUrlParams": true
+}
+</script>
+```
+
 ## Configuration Script
 <a name="script"></a>
 
@@ -406,4 +427,10 @@ import { getTimezone } from "@ui5/webcomponents-base/dist/config/Timezone.js";
 
 ```js
 import { getThemeRoot, setThemeRoot } from "@ui5/webcomponents-base/dist/config/ThemeRoot.js";
+```
+
+ - `ignoreUrlParams`
+
+```js
+import { getIgnoreUrlParams, setIgnoreUrlParams } from "@ui5/webcomponents-base/dist/config/UrlParams.js";
 ```

packages/base/cypress/specs/ConfigurationURL.cy.tsx

@@ -521,3 +521,57 @@ describe("Some settings can be set via SAP UI URL params", () => {
 			.should("equal", "sap_fiori_3_hcb");
 	});
 });
+
+describe("URL parameters are ignored when ignoreUrlParams is set", () => {
+	before(() => {
+		const searchParams = "sap-ui-language=de&sap-ui-theme=sap_horizon_hcb&sap-ui-animationMode=none";
+
+		cy.stub(internals, "search").callsFake(() => {
+			return searchParams;
+		});
+
+		cy.window()
+			.then($el => {
+				const scriptElement = document.createElement("script");
+				scriptElement.type = "application/json";
+				scriptElement.setAttribute("data-ui5-config", "true");
+				scriptElement.innerHTML = JSON.stringify({
+					language: "fr",
+					animationMode: "basic",
+					ignoreUrlParams: true,
+				});
+				return $el.document.head.append(scriptElement);
+			});
+
+		cy.wrap({ resetConfiguration })
+			.invoke("resetConfiguration", true);
+
+		cy.mount(<TestGeneric />);
+	});
+
+	after(() => {
+		cy.window()
+			.then($el => {
+				const scriptElement = $el.document.head.querySelector("script[data-ui5-config]");
+				scriptElement?.remove();
+			});
+	});
+
+	it("Tests that URL language param is ignored and script value is used", () => {
+		cy.wrap({ getLanguage })
+			.invoke("getLanguage")
+			.should("equal", "fr");
+	});
+
+	it("Tests that URL theme param is ignored", () => {
+		cy.wrap({ getTheme })
+			.invoke("getTheme")
+			.should("not.equal", "sap_horizon_hcb");
+	});
+
+	it("Tests that URL animationMode param is ignored and script value is used", () => {
+		cy.wrap({ getAnimationMode })
+			.invoke("getAnimationMode")
+			.should("equal", AnimationMode.Basic);
+	});
+});

packages/base/src/InitialConfiguration.ts

@@ -24,6 +24,7 @@ type InitialConfig = {
 	fetchDefaultLanguage: boolean,
 	defaultFontLoading: boolean,
 	enableDefaultTooltips: boolean,
+	ignoreUrlParams: boolean,
 };
 
 let initialConfig: InitialConfig = {
@@ -40,6 +41,7 @@ let initialConfig: InitialConfig = {
 	fetchDefaultLanguage: false,
 	defaultFontLoading: true,
 	enableDefaultTooltips: true,
+	ignoreUrlParams: false,
 };
 
 /* General settings */
@@ -88,6 +90,11 @@ const getEnableDefaultTooltips = () => {
 	return initialConfig.enableDefaultTooltips;
 };
 
+const getIgnoreUrlParams = () => {
+	initConfiguration();
+	return initialConfig.ignoreUrlParams;
+};
+
 /**
  * Get the configured calendar type
  * @returns { String } the name of the configured calendar type
@@ -226,7 +233,9 @@ const resetConfiguration = (testEnv?: boolean) => {
 	parseConfigurationScript();
 
 	// 2. URL parameters overwrite configuration script parameters
-	parseURLParameters();
+	if (!initialConfig.ignoreUrlParams) {
+		parseURLParameters();
+	}
 
 	// 3. If OpenUI5 is detected, it has the highest priority
 	applyOpenUI5Configuration();
@@ -246,4 +255,5 @@ export {
 	getDefaultFontLoading,
 	resetConfiguration,
 	getEnableDefaultTooltips,
+	getIgnoreUrlParams,
 };

packages/base/src/config/UrlParams.ts

@@ -0,0 +1,37 @@
+import { getIgnoreUrlParams as getConfiguredIgnoreUrlParams } from "../InitialConfiguration.js";
+
+let _ignoreUrlParams: boolean;
+
+/**
+ * Returns if the "ignoreUrlParams" configuration is set.
+ * @public
+ * @since 2.23.0
+ * @returns { boolean }
+ */
+const getIgnoreUrlParams = (): boolean => {
+	if (_ignoreUrlParams === undefined) {
+		_ignoreUrlParams = getConfiguredIgnoreUrlParams();
+	}
+
+	return _ignoreUrlParams;
+};
+
+/**
+ * Defines the "ignoreUrlParams" setting.
+ *
+ * - When set to "true", the framework will not process URL parameters
+ * (e.g. sap-ui-theme, sap-ui-language) during initialization.
+ * - When set to "false" (default), URL parameters are processed normally.
+ *
+ * @public
+ * @since 2.23.0
+ * @param { boolean } ignoreUrlParams
+ */
+const setIgnoreUrlParams = (ignoreUrlParams: boolean) => {
+	_ignoreUrlParams = ignoreUrlParams;
+};
+
+export {
+	getIgnoreUrlParams,
+	setIgnoreUrlParams,
+};

packages/base/src/index.ts

@@ -24,6 +24,7 @@ import {
 	getFetchDefaultLanguage,
 } from "./config/Language.js";
 import { getNoConflict, setNoConflict } from "./config/NoConflict.js";
+import { getIgnoreUrlParams, setIgnoreUrlParams } from "./config/UrlParams.js";
 import {
 	getTheme,
 	setTheme,
@@ -133,6 +134,8 @@ export {
 	getFetchDefaultLanguage,
 	getNoConflict,
 	setNoConflict,
+	getIgnoreUrlParams,
+	setIgnoreUrlParams,
 	getTheme,
 	setTheme,
 	getDefaultTheme,