@openui5/sap.ui.core 1.131.0 → 1.132.0

package/src/sap/ui/core/Fragment.js

@@ -1,6 +1,6 @@
 /*!
  * OpenUI5
- * (c) Copyright 2009-2024 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2025 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -99,7 +99,7 @@ function(
 	 * @class
 	 * @extends sap.ui.base.ManagedObject
 	 * @author SAP SE
-	 * @version 1.131.0
+	 * @version 1.132.0
 	 * @public
 	 * @alias sap.ui.core.Fragment
 	 */
@@ -333,65 +333,84 @@ function(
 	// ###   Factory functions   ###
 
 	/**
-	 * Instantiate a Fragment - this method loads the Fragment content, instantiates it, and returns this content.
-	 * The Fragment object itself is not an entity which has further significance beyond this constructor.
+	 * Loads and instantiates a fragment.
+	 * The fragment object itself is not an entity that has any further significance beyond this factory function.
 	 *
-	 * To instantiate an existing Fragment, call this method as:
-	 *    sap.ui.fragment(sName, sType, [oController]);
-	 * The sName must correspond to a Fragment module which can be loaded
-	 * via the module system (fragmentName + suffix ".fragment.[typeextension]") and which defines the Fragment content.
-	 * If oController is given, the (event handler) methods referenced in the Fragment will be called on this controller.
-	 * Note that Fragments may require a Controller to be given and certain methods to be available.
+	 * To instantiate a fragment that is already defined separately, call:
+	 * <pre>
+	 * sap.ui.fragment(sName, sType, oController?);
+	 * </pre>
 	 *
-	 * The Fragment types "XML", "JS" and "HTML" are available by default; additional Fragment types can be implemented
-	 * and added using the sap.ui.core.Fragment.registerType() function.
+	 * Advanced usage to give further configuration options:
+	 * <pre>
+	 * sap.ui.fragment(oFragmentConfig, oController?);
+	 * </pre>
+	 * In addition to <code>id</code> and <code>type</code>, the <code>oFragmentConfig</code> object
+	 * can have either a <code>fragmentName</code> or a <code>fragmentContent</code> property, but not both.
 	 *
+	 * To define a fragment ID, which can be used as a prefix for the created control IDs,
+	 * you must use either the above advanced version with an <code>id</code> or one of the typed factory functions
+	 * like {@link sap.ui.xmlfragment} or {@link sap.ui.jsfragment}.
 	 *
-	 * Advanced usage:
-	 * To instantiate a Fragment and give further configuration options, call this method as:
-	 *     sap.ui.fragment(oFragmentConfig, [oController]);
-	 * The oFragmentConfig object can have the following properties:
-	 * - "fragmentName": the name of the Fragment, as above
-	 * - "fragmentContent": the definition of the Fragment content itself. When this property is given, any given name is ignored.
-	 *         The type of this property depends on the Fragment type, e.g. it could be a string for XML Fragments.
-	 * - "type": the type of the Fragment, as above (mandatory)
-	 * - "id": the ID of the Fragment (optional)
-	 * Further properties may be supported by future or custom Fragment types. Any given properties
-	 * will be forwarded to the Fragment implementation.
+	 * A fragment type must be given in all cases. The fragment types <code>"XML"</code>, <code>"JS"</code>, and <code>"HTML"</code> (type <code>"HTML"</code> is deprecated)
+	 * are available by default. Additional fragment types can be implemented and added using the {@link sap.ui.core.Fragment.registerType} function.
 	 *
-	 * If you want to give a fixed ID for the Fragment, please use the advanced version of this method call with the
-	 * configuration object or use the typed factories like sap.ui.xmlfragment(...) or sap.ui.jsfragment(...).
-	 * Otherwise the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the ID of
-	 * all contained controls.
+	 * Custom fragment types can support further properties. Any given properties will be forwarded to the fragment implementation.
+	 *
+	 * The optional <code>oController</code> can be either the controller of an enclosing view,
+	 * a new controller instance, or a simple object with the necessary methods attached.
+	 * Note that a fragment has no runtime representation besides its contained controls. Therefore, there is no API to retrieve the controller from the return value.
+	 * Note also that fragments may require a controller to be given and certain methods to be available.
+	 *
+	 * <b>Note:</b>
+	 * In case you are embedding a Fragment into an existing View, please also have a look at the
+	 * {@link sap.ui.core.mvc.Controller.loadFragment loadFragment} factory for a closer coupling to the corresponding Controller instance.
 	 *
-	 * @param {string|Object} sName the Fragment name
-	 * @param {string} sType the Fragment type, e.g. "XML", "JS", or "HTML"
-	 * @param {sap.ui.core.mvc.Controller|Object} [oController] the Controller or Object which should be used by the controls in the Fragment.
-	 *     Note that some Fragments may not need a Controller and other may need one - and even rely on certain methods implemented in the Controller.
+	 * @param {string|object} vName
+	 *         resource name of the fragment module in dot notation without the <code>.fragment.<i>&lt;typeExtension></i></code> suffix from the file name.
+	 *         Alternatively, a configuration object as specified below
+	 * @param {string} [vName.id]
+	 *         optional ID of the created fragment
+	 * @param {string|object} [vName.fragmentContent]
+	 *         definition of the fragment content that will be used instead of loading the content from a separate file.
+	 *         The type of this property depends on the fragment type. For example, it could be a string for XML fragments or an object for JS fragments
+	 * @param {string} [vName.fragmentName]
+	 *         recource name of the fragment module as specified above
+	 * @param {string} vName.type
+	 *         type of the fragment, for example, <code>"XML"</code>, <code>"JS"</code>, <code>"HTML"</code>, or any other type that has been implemented additionally
+	 * @param {string|sap.ui.core.mvc.Controller|object} vType
+	 *         type of the fragment as specified by <code>vName.type</code> or, in the advanced usage case, an optional <code>oController</code>
+	 * @param {sap.ui.core.mvc.Controller|object} [oController]
+	 *         controller object to be used for methods or event handlers referenced in the fragment
 	 * @public
 	 * @static
-	 * @deprecated since 1.58, use {@link sap.ui.core.Fragment.load} instead
-	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} the root Control(s) of the Fragment content
+	 * @deprecated As of version 1.58. Refer to {@link topic:04129b2798c447368f4c8922c3c33cd7 Instantiation of Fragments}.
+	 * @returns {sap.ui.core.Control|sap.ui.core.Control[]} the instantiated root control(s) from the fragment content
 	 * @ui5-global-only
 	 */
-	sap.ui.fragment = function (sName, sType, oController) {
+	sap.ui.fragment = function (vName, vType, oController) {
 
 		var sFragmentType;
-		if (typeof (sType) === "string") {
-			sFragmentType = sType.toLowerCase();
-		} else if (typeof (sType) === "object" && typeof (sType.fragmentName) === "string") {
-			sFragmentType = sType.fragmentName.toLowerCase();
+		if (typeof vType === "string") {
+			sFragmentType = vType.toLowerCase();
+		} else if (typeof vName === "object" && typeof vName.type === "string") {
+			sFragmentType = vName.type.toLowerCase();
 		} else {
 			sFragmentType = "";
 		}
-		Log.info("Do not use deprecated factory function 'sap.ui." + sFragmentType + "fragment'. Require 'sap/ui/core/Fragment' and use 'load()' instead", "sap.ui." + sFragmentType + "fragment", null, function () {
-			return {
+		Log.info("Do not use deprecated factory function 'sap.ui." + sFragmentType + "fragment'.", "sap.ui." + sFragmentType + "fragment", null, function () {
+			var oSupportInfo = {
 				type: "sap.ui." + sFragmentType + "fragment",
-				name: sFragmentType ? sName + ".fragment." + sFragmentType : sName
+				name: ( vName.fragmentName || vName ) + ".fragment." + sFragmentType
 			};
+			if (vName.fragmentContent) {
+				oSupportInfo.content = vName.fragmentContent;
+				oSupportInfo.name = "";
+			}
+			return oSupportInfo;
 		});
 
-		return fragmentFactory(sName, sType, oController);
+		return fragmentFactory(vName, vType, oController);
 	};
 
 	/**
@@ -400,7 +419,7 @@ function(
 	 * @private
 	 * @param {string|object} vName The fragment name or the fragment config
 	 * @param {string|sap.ui.core.mvc.Controller} vType The type of the fragment or the controller
-	 * @param {sap.ui.core.mvc.Controller|Object} oController the Controller or Object which should be used by the controls in the Fragment.
+	 * @param {sap.ui.core.mvc.Controller|object} oController the Controller or object which should be used by the controls in the Fragment.
 	 * @returns {Promise<sap.ui.core.Control|sap.ui.core.Control[]>|sap.ui.core.Fragment} If fragment is created asynchronoulsy
 	 *  a Promise is returned which resolves with the resulting {sap.ui.core.Control|sap.ui.core.Control[]}
 	 *  after fragment parsing and instantiation.
@@ -465,29 +484,35 @@ function(
 	}
 
 	/**
-	 * Loads and instantiates a Fragment.
-	 * A Promise is returned, which resolves with the Fragments content.
+	 * Loads and instantiates a fragment.
+	 * Also refer to {@link topic:04129b2798c447368f4c8922c3c33cd7 Instantiation of Fragments}.
 	 *
-	 * The Fragment object itself is not an entity with significance beyond this factory.
+	 * The fragment object itself is not an entity that has any further significance beyond this factory function.
 	 *
-	 * The Fragment types "XML", "JS" and "HTML" (type "HTML" is deprecated) are available by default; additional Fragment types can be added using
-	 * the sap.ui.core.Fragment.registerType() function.
+	 * A Promise is returned, which resolves with the fragment's content.
+	 *
+	 * The Fragment types <code>"XML"</code>, <code>"JS"</code>, and <code>"HTML"</code> (type <code>"HTML"</code> is deprecated) are available by default.
+	 * Additional Fragment types can be implemented and added using the {@link sap.ui.core.Fragment.registerType} function.
 	 *
 	 * Further properties may be supported by future or custom Fragment types. Any given properties
 	 * will be forwarded to the Fragment implementation.
 	 *
-	 * If no fixed ID is given, the Fragment ID is generated. In any case, the Fragment ID will be used as prefix for the IDs of
+	 * If no fixed ID is given, the fragment ID is generated. In any case, the fragment ID will be used as prefix for the IDs of
 	 * all contained controls.
 	 *
+	 * <b>Note:</b>
+	 * In case you are embedding a Fragment into an existing View, please also have a look at the
+	 * {@link sap.ui.core.mvc.Controller.loadFragment loadFragment} factory for a closer coupling to the corresponding Controller instance.
+	 *
 	 * @example <caption>Loading an XML fragment (default type)</caption>
-	 * sap.ui.require(["sap/ui/core/Fragment"], async function(Fragment){
+	 * sap.ui.require(["sap/ui/core/Fragment"], async (Fragment) => {
 	 *  const myFrag = await Fragment.load({
 	 *    name: "my.useful.VerySimpleUiPart"
 	 *  });
 	 * });
 	 *
 	 * @example <caption>Creating an XML fragments</caption>
-	 * sap.ui.require(["sap/ui/core/Fragment"], async function(Fragment){
+	 * sap.ui.require(["sap/ui/core/Fragment"], async (Fragment) => {
 	 *  const myFrag = await Fragment.load({
 	 *    type: "XML",
 	 *    definition: '&lt;Button xmlns=&quot;sap.m&quot; id=&quot;xmlfragbtn&quot; text=&quot;This is an XML Fragment&quot; press=&quot;doSomething&quot;&gt;&lt;/Button&gt;'
@@ -495,7 +520,7 @@ function(
 	 * });
      *
 	 * @example <caption>Creating an JS fragments</caption>
-	 * sap.ui.require(["sap/ui/core/Fragment"], async function(Fragment){
+	 * sap.ui.require(["sap/ui/core/Fragment"], async (Fragment) => {
 	 *  const myFrag = await Fragment.load({
      *    name: "my.sample.AsyncButton",
 	 *    type: "JS",
@@ -503,29 +528,29 @@ function(
 	 * });
 	 *
 	 * @example <caption>Creating an HTML fragments (deprecated)</caption>
-	 * sap.ui.require(["sap/ui/core/Fragment"], async function(Fragment){
+	 * sap.ui.require(["sap/ui/core/Fragment"], async (Fragment) => {
 	 *  const myFrag = await Fragment.load({
 	 *    type: "HTML",
 	 *    definition: '&lt;div id=&quot;htmlfragbtn&quot; data-sap-ui-type=&quot;sap.m.Button&quot; data-text=&quot;This is an HTML Fragment&quot;&gt;&lt;/div&gt;'
 	 *  });
 	 * });
 	 *
-	 * <b>Note:</b> If the Fragment contains ExtensionPoints you have to pass the parameter 'containingView'.
+	 * <b>Note:</b> If the fragment contains <code>ExtensionPoint</code>s, you have to pass the parameter <code>containingView</code>.
 	 * The containing view should be the View instance into which the fragment content will be inserted manually.
 	 *
 	 * @param {object} mOptions options map
-	 * @param {string} [mOptions.name] must be supplied if no "definition" parameter is given. The Fragment name must correspond to an XML Fragment which
+	 * @param {string} [mOptions.name] must be supplied if no <code>definition</code> parameter is given. The fragment name must correspond to an XML fragment which
 	 *    can be loaded via the module system
-	 *    (fragmentName + suffix ".fragment.[typeextension]") and which contains the Fragment definition.
-	 *    If "mOptions.controller" is supplied, the (event handler-) methods referenced in the Fragment will be called on this Controller.
-	 *    Note that Fragments may require a Controller to be given and certain methods to be implemented by it.
-	 * @param {string} [mOptions.type=XML] the Fragment type, e.g. "XML", "JS", or "HTML" (type "HTML" is deprecated). Default is "XML"
-	 * @param {string} [mOptions.definition] definition of the Fragment content. When this property is supplied, the "name" parameter must not be used. If both are supplied, the definition has priority.
-	 * Please see the above example on how to use the 'definition' parameter.
-	 * @param {string} [mOptions.id] the ID of the Fragment
-	 * @param {sap.ui.core.mvc.Controller|Object} [mOptions.controller] the Controller or Object which should be used by the controls in the Fragment.
-	 *    Note that some Fragments may not need a Controller while others may need one and certain methods to be implemented by it.
-	 * @param {sap.ui.core.mvc.View} [mOptions.containingView] The view containing the Fragment content. If the Fragment content contains ExtensionPoints this parameter must be given.
+	 *    (fragmentName + suffix <code>.fragment.<i>&lt;typeExtension></i></code>) and which contains the fragment definition.
+	 *    If <code>mOptions.controller</code> is supplied, the (event handler) methods referenced in the fragment will be called on that controller.
+	 *    Note that fragments may require a controller to be given and certain methods to be implemented by it.
+	 * @param {string} [mOptions.type=XML] the fragment type, e.g. <code>"XML"</code>, <code>"JS"</code>, or <code>"HTML"</code> (type <code>"HTML"</code> is deprecated). Default is <code>"XML"</code>
+	 * @param {string} [mOptions.definition] definition of the fragment content. When this property is supplied, the <code>name</code> parameter must not be used. If both are supplied, the definition has priority.
+	 * Please see the above example on how to use the <code>definition</code> parameter.
+	 * @param {string} [mOptions.id] the ID of the fragment
+	 * @param {sap.ui.core.mvc.Controller|object} [mOptions.controller] the controller or object which should be used by the controls in the fragment.
+	 *    Note that some fragments may not need a controller while others may need one and certain methods to be implemented by it.
+	 * @param {sap.ui.core.mvc.View} [mOptions.containingView] The view containing the fragment content. If the fragment content contains <code>ExtensionPoint</code>s, this parameter must be given.
 	 * @public
 	 * @static
 	 * @since 1.58
@@ -578,128 +603,108 @@ function(
 	};
 
 	/**
-	 * Instantiates an XML-based Fragment.
+	 * Loads and instantiates an XML-based fragment.
 	 *
-	 * To instantiate a fragment, call:
+	 * To instantiate a fragment that is already defined separately, call:
 	 * <pre>
-	 *    sap.ui.xmlfragment([sId], sFragmentName, [oController]);
+	 * sap.ui.xmlfragment(sId?, sFragmentName, oController?);
 	 * </pre>
-	 * The fragment instance ID is optional and will be used as prefix for the ID of all contained controls.
-	 * If no ID is passed, controls will not be prefixed. The <code>sFragmentName</code> must correspond to an
-	 * XML fragment which can be loaded via the module system (fragmentName + ".fragment.xml") and which defines
-	 * the fragment. If <code>oController</code> is given, the methods referenced in the fragment will be called
-	 * on this controller.
 	 *
-	 * Note that fragments may require a controller to be given and certain methods to be available.
-	 *
-	 *
-	 * <h3>Advanced usage:</h3>
-	 * To instantiate a fragment and optionally directly give the XML definition instead of loading it from a file,
-	 * call:
+	 * Advanced usage:
 	 * <pre>
-	 *     sap.ui.xmlfragment(oFragmentConfig, [oController]);
+	 * sap.ui.xmlfragment(oFragmentConfig, oController?);
 	 * </pre>
-	 * The <code>oFragmentConfig</code> object can either have a <code>fragmentName</code> or a <code>fragmentContent</code>
-	 * property, but not both. <code>fragmentContent</code> can hold the fragment definition as XML string; if not given,
-	 * <code>fragmentName</code> must be given and the fragment content definition is loaded via the module system.
-	 * Again, if <code>oController</code> is given, the methods referenced in the fragment will be called on this controller.
+	 * In addition to an <code>id</code>, the <code>oFragmentConfig</code> object can have either a <code>fragmentName</code>
+	 * or a <code>fragmentContent</code> property, but not both.
 	 *
-	 * @param {string} [sId]
-	 *            ID of the newly created fragment
-	 * @param {string | object} vFragment
-	 *            Resource name of the fragment; a module name in dot notation without the '.fragment.xml' suffix.
-	 *            Alternatively, a configuration object can be given with the properties described below. In this case,
-	 *            no <code>sId</code> may be given as first parameter, but as property <code>id</code> in the configuration
-	 *            object.
-	 * @param {string} [vFragment.id]
-	 *            ID of the newly created fragment; will be used as a prefix to all contained control IDs
-	 * @param {string} [vFragment.fragmentName]
-	 *            Resource name of the fragment; a module name in dot notation without the '.fragment.html' suffix
-	 * @param {string} [vFragment.fragmentContent]
-	 *            Definition of the fragment as an XML string
+	 * @param {string|object} [vId]
+	 *            ID of the created fragment which will be used as prefix to all contained control IDs.
+	 *            If the first argument is not an ID, it must be either the fragment name (<code>sFragmentName</code>)
+	 *            or a configuration object (<code>oFragmentConfig</code>) as specified below
+	 * @param {string} [vId.id]
+	 *            ID of the created fragment which will be used as prefix to all contained control IDs
+	 * @param {string} [vId.fragmentContent]
+	 *            definition of the fragment content as an XML string that will be used
+	 *            instead of loading the content from a separate <code>.fragment.xml</code> file.
+	 *            When this property is given, any given fragment name is ignored
+	 * @param {string} [vId.fragmentName]
+	 *            resource name of the fragment module in dot notation without the <code>.fragment.xml</code> suffix from the file name
+	 * @param {string|sap.ui.core.mvc.Controller|object} vFragment
+	 *            resource name of the fragment module as specified by <code>vId.fragmentName</code> or,
+	 *            in the advanced usage case, an optional <code>oController</code>
 	 * @param {sap.ui.core.mvc.Controller|object} [oController]
-	 *            A controller to be used for event handlers in the fragment; can either be the controller of an
+	 *            controller object to be used for methods or event handlers. Can be either the controller of an
 	 *            enclosing view, a new controller instance, or a simple object with the necessary methods attached.
-	 *            Note that a fragment has no runtime representation besides its contained controls. There's
-	 *            therefore no API to retrieve the controller after creating a fragment
+	 *            Note that a fragment has no runtime representation besides its contained controls. Therefore, there is
+	 *            no API to retrieve the controller from the return value.
+	 *            Note also that fragments may require a controller to be given and certain methods to be available
 	 * @public
 	 * @static
-	 * @deprecated since 1.58, use {@link sap.ui.core.Fragment.load} instead
-	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} the root Control(s) of the created fragment instance
+	 * @deprecated As of version 1.58. Refer to {@link topic:04129b2798c447368f4c8922c3c33cd7 Instantiation of Fragments}.
+	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} the instantiated root control(s) from the fragment content
 	 * @ui5-global-only
 	 */
-	sap.ui.xmlfragment = function(sId, vFragment, oController) {
+	sap.ui.xmlfragment = function(vId, vFragment, oController) {
 
-		if (typeof (sId) === "string") { // basic call
+		if (typeof (vId) === "string") { // basic call
 			if (typeof (vFragment) === "string") { // with ID
-				return sap.ui.fragment({fragmentName: vFragment, sId: sId, type: "XML"}, oController); // legacy-relevant
+				return sap.ui.fragment({fragmentName: vFragment, sId: vId, type: "XML"}, oController); // legacy-relevant
 
 			} else { // no ID, sId is actually the name and vFragment the optional Controller
-				return sap.ui.fragment(sId, "XML", vFragment); // legacy-relevant
+				return sap.ui.fragment(vId, "XML", vFragment); // legacy-relevant
 			}
 		} else { // advanced call
-			sId.type = "XML";
+			vId.type = "XML";
 			 // second parameter "vFragment" is the optional Controller
-			return sap.ui.fragment(sId, vFragment); // legacy-relevant
+			return sap.ui.fragment(vId, vFragment); // legacy-relevant
 		}
 	};
 
 
 	/**
-	 * Defines OR instantiates an HTML-based fragment.
+	 * Defines <strong>or</strong> instantiates a JS-based fragment.
 	 *
 	 * To define a JS fragment, call:
 	 * <pre>
-	 *    sap.ui.jsfragment(sName, oFragmentDefinition)
+	 * sap.ui.jsfragment(sName, oFragmentDefinition);
 	 * </pre>
-	 * where:
-	 * <ul>
-	 * <li><code>sName</code> is the name by which this fragment later can be found and instantiated. If defined in
-	 *   its own file, in order to be found by the module loading system, the file location and name must correspond
-	 *   to <code>sName</code> (path + file name must be: fragmentName + ".fragment.js"). </li>
-	 * <li><code>oFragmentDefinition</code> is an object at least holding the <code>createContent(oController)</code>
-	 *   method which defines the fragment content. If given during instantiation, the <code>createContent</code>
-	 *   method receives a controller instance (otherwise, parameter <code>oController</code> will be undefined)
-	 *   and the return value must be one <code>sap.ui.core.Control</code> (which could have any number of children).</li>
-	 * </ul>
 	 *
-	 * To instantiate a JS fragment, call:
+	 * To instantiate a JS fragment that is already defined, call:
 	 * <pre>
-	 *    sap.ui.jsfragment([sId], sFragmentName, [oController]);
+	 * sap.ui.jsfragment(sId?, sFragmentName, oController?);
+	 * </pre>
+	 * Advanced usage:
+	 * <pre>
+	 * sap.ui.jsfragment(oFragmentConfig, oController?);
 	 * </pre>
-	 * The fragment ID is optional (generated if not given) and the fragment implementation <i>can</i> use it
-	 * to make contained controls unique (this depends on the implementation: some JS fragments may choose
-	 * not to support multiple instances within one application and not use the ID prefixing).
-	 * The <code>sFragmentName</code> must correspond to a JS fragment which can be loaded via the module system
-	 * (<code>sFragmentName</code> converted to a path + ".fragment.js" suffix) and which defines the fragment.
-	 * Or it can be a name that has been used earlier to define a fragment of that name.
-	 * If <code>oController</code> is given, the methods referenced in the fragment will be called on this controller.
-	 * Note that fragments may require a controller to be given and certain methods to be available.
 	 *
 	 *
 	 * @param {string|object} vName
-	 *            Name of the fragment when defining a fragment; ID or name or configuration object when instantiating
-	 *            a fragment
+	 *            when defining a fragment: name of the fragment.<br>
+	 *            When loading a fragment: fragment ID (optional), fragment name, or configuration object as specified below
 	 * @param {string} [vName.id]
-	 *            ID of the newly created fragment; will be used as a prefix to all contained control IDs
-	 * @param {string} [vName.fragmentName]
-	 *            Name of the fragment. When no fragment has been defined with that name, the name will be converted
-	 *            to a path by replacing dots with slashes and appending '.fragment.js'. The corresponding resource will
-	 *            be loaded and is expected to define a fragment with the <code>fragmentName</code>
-	 * @param {object|string} [vFragmentDefinition]
-	 *            When defining a fragment, this parameter must be a factory object that will be used to create new
-	 *            instances of the fragment; it must at least contain a <code>createContent</code> method.
-	 *            When creating an instance of a fragment and when <code>vName</code> was an ID, this parameter
-	 *            must be the name of the fragment. When the first parameter was a name, this parameter must be omitted.
+	 *            ID of the newly created fragment which <i>can</i> be used as a prefix
+	 *            when creating the IDs in the JS fragment content. Even if an <code>id</code> is given, some JS fragments may choose
+	 *            not to use the ID prefixing, for example, in order to prevent the fragment from being instantiated multiple times
+	 *            within the lifecycle of the existing fragment
+	 * @param {string} vName.fragmentName
+	 *            resource name of the fragment module in dot notation without the <code>.fragment.js</code> suffix from the file name.
+	 *            When no fragment has been defined with that name, the name will be converted
+	 *            to a path by replacing dots with slashes and appending <code>.fragment.js</code>. The corresponding resource to load
+	 *            is expected to have a fragment defined with the same <code>fragmentName</code>
+	 * @param {object|string} vFragmentDefinition
+	 *            when defining a fragment: object holding at least the <code>createContent(oController?)</code>
+	 *            method that returns an instance of <code>sap.ui.core.Control</code> or an array thereof.<br>
+	 *            When loading a fragment and the first argument is an ID: the <code>fragmentName</code>
 	 * @param {sap.ui.core.mvc.Controller|object} [oController]
-	 *            A controller to be used for event handlers in the fragment; can either be the controller of an
+	 *            controller object to be used for methods or event handlers. Can be either the controller of an
 	 *            enclosing view, a new controller instance, or a simple object with the necessary methods attached.
-	 *            Note that a fragment has no runtime representation besides its contained controls. There's therefore
-	 *            no API to retrieve the controller after creating a fragment
+	 *            Note that a fragment has no runtime representation besides its contained controls. Therefore, there is
+	 *            no API to retrieve the controller from the return value
 	 * @public
 	 * @static
-	 * @deprecated since 1.58, use {@link sap.ui.core.Fragment.load} instead
-	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} The root control(s) of the created fragment instance
+	 * @deprecated As of version 1.58. Refer to {@link topic:04129b2798c447368f4c8922c3c33cd7 Instantiation of Fragments}.
+	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} the instantiated root control(s) from the fragment content
 	 * @ui5-global-only
 	 */
 	sap.ui.jsfragment = function(vName, vFragmentDefinition, oController) { // definition of a JS Fragment
@@ -737,67 +742,61 @@ function(
 
 
 	/**
-	 * Instantiates an HTML-based Fragment.
+	 * Loads and instantiates an HTML-based fragment.
 	 *
-	 * To instantiate a fragment, call:
+	 * To instantiate a fragment that is already defined separately, call:
 	 * <pre>
-	 *    sap.ui.htmlfragment([sId], sFragmentName, [oController]);
+	 * sap.ui.htmlfragment(sId?, sFragmentName, oController?);
 	 * </pre>
-	 * The fragment instance ID is optional and will be used as prefix for the ID of all
-	 * contained controls. If no ID is passed, controls will not be prefixed.
-	 * The <code>sFragmentName</code> must correspond to an HTML fragment which can be loaded
-	 * via the module system (fragmentName + ".fragment.html") and which defines the fragment.
-	 * If <code>oController</code> is given, the methods referenced in the fragment will be called on this controller.
-	 * Note that fragments may require a controller to be given and certain methods to be available.
 	 *
-	 * <h3>Advanced usage:</h3>
-	 * To instantiate a fragment and optionally directly give the HTML definition instead of loading it from a file,
-	 * call:
+	 * Advanced usage:
 	 * <pre>
-	 *     sap.ui.htmlfragment(oFragmentConfig, [oController]);
+	 * sap.ui.htmlfragment(oFragmentConfig, oController?);
 	 * </pre>
-	 * The <code>oFragmentConfig</code> object can either have a <code>fragmentName</code> or a <code>fragmentContent</code>
-	 * property, but not both of them. <code>fragmentContent</code> can hold the fragment definition as XML string; if not
-	 * given, <code>fragmentName</code> must be given and the fragment content definition is loaded by the module system.
-	 * Again, if <code>oController</code> is given, any methods referenced in the fragment will be called on this controller.
+	 * In addition to an <code>id</code>, the <code>oFragmentConfig</code> object can have either a <code>fragmentName</code>
+	 * or a <code>fragmentContent</code> property, but not both.
 	 *
-	 * @param {string} [sId]
-	 *            ID of the newly created fragment
-	 * @param {string | object} vFragment
-	 *            Resource name of the fragment, a module name in dot notation without the '.fragment.html' suffix.
-	 *            Alternatively, a configuration object can be given with the properties described below. In this case,
-	 *            no <code>sId</code> may be given as first parameter, but as property <code>id</code> in the configuration
-	 *            object.
-	 * @param {string} [vFragment.id]
-	 *            ID of the newly created fragment; will be used as a prefix to all contained control IDs
-	 * @param {string} [vFragment.fragmentName]
-	 *            Resource name of the Fragment; a module name in dot notation without the '.fragment.html' suffix
-	 * @param {string} [vFragment.fragmentContent]
-	 *            Definition of the fragment as an HTML string
+	 * @param {string|object} [vId]
+	 *            ID of the created fragment which will be used as prefix to all contained control IDs.
+	 *            If the first argument is not an ID, it must be either the fragment name (<code>sFragmentName</code>)
+	 *            or a configuration object (<code>oFragmentConfig</code>) as specified below
+	 * @param {string} [vId.id]
+	 *            ID of the created fragment which will be used as prefix to all contained control IDs
+	 * @param {string} [vId.fragmentContent]
+	 *            definition of the fragment content as an HTML string that will be used
+	 *            instead of loading the content from a separate <code>.fragment.html</code> file.
+	 *            When this property is given, any given fragment name is ignored
+	 * @param {string} [vId.fragmentName]
+	 *            resource name of the fragment module in dot notation without the <code>.fragment.html</code> suffix from the file name
+	 * @param {string|sap.ui.core.mvc.Controller|object} vFragment
+	 *            resource name of the fragment module as specified by <code>vId.fragmentName</code> or,
+	 *            in the advanced usage case, an optional <code>oController</code>
 	 * @param {sap.ui.core.mvc.Controller|object} [oController]
-	 *            A controller to be used for event handlers in the fragment; can either be the controller of an
+	 *            controller object to be used for methods or event handlers. Can be either the controller of an
 	 *            enclosing view, a new controller instance, or a simple object with the necessary methods attached.
-	 *            Note that a fragment has no runtime representation besides its contained controls. There's therefore
-	 *            no API to retrieve the controller after creating a fragment
+	 *            Note that a fragment has no runtime representation besides its contained controls. Therefore, there is
+	 *            no API to retrieve the controller from the return value.
+	 *            Note also that fragments may require a controller to be given and certain methods to be available
 	 * @public
 	 * @static
-	 * @deprecated since 1.58, use {@link sap.ui.core.Fragment.load} instead
-	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} Root control or controls of the created fragment instance
+	 * @deprecated As of version 1.58. Additionally, use of fragments based on type <code>"HTML"</code> is deprecated since 1.108.
+	 *    If you need declarative fragments, use XML fragments instead. Refer to {@link topic:04129b2798c447368f4c8922c3c33cd7 Instantiation of Fragments}.
+	 * @return {sap.ui.core.Control|sap.ui.core.Control[]} the instantiated root control(s) from the fragment content
 	 * @ui5-global-only
 	 */
-	sap.ui.htmlfragment = function(sId, vFragment, oController) {
+	sap.ui.htmlfragment = function(vId, vFragment, oController) {
 
-		if (typeof (sId) === "string") { // basic call
+		if (typeof (vId) === "string") { // basic call
 			if (typeof (vFragment) === "string") { // with ID
-				return sap.ui.fragment({fragmentName: vFragment, sId: sId, type: "HTML"}, oController);  // legacy-relevant
+				return sap.ui.fragment({fragmentName: vFragment, sId: vId, type: "HTML"}, oController);  // legacy-relevant
 
-			} else { // no ID, sId is actually the name and vFragment the optional Controller
-				return sap.ui.fragment(sId, "HTML", vFragment); // legacy-relevant
+			} else { // no ID, vId is actually the name and vFragment the optional Controller
+				return sap.ui.fragment(vId, "HTML", vFragment); // legacy-relevant
 			}
 		} else { // advanced call
-			sId.type = "HTML";
+			vId.type = "HTML";
 			// second parameter "vFragment" is the optional Controller
-			return sap.ui.fragment(sId, vFragment); // legacy-relevant
+			return sap.ui.fragment(vId, vFragment); // legacy-relevant
 		}
 	};
 

package/src/sap/ui/core/HTML.js

@@ -1,6 +1,6 @@
 /*!
  * OpenUI5
- * (c) Copyright 2009-2024 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2025 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -44,7 +44,7 @@ sap.ui.define([
 	 * @extends sap.ui.core.Control
 	 *
 	 * @author SAP SE
-	 * @version 1.131.0
+	 * @version 1.132.0
 	 *
 	 * @public
 	 * @alias sap.ui.core.HTML

package/src/sap/ui/core/HTMLRenderer.js

@@ -1,6 +1,6 @@
 /*!
  * OpenUI5
- * (c) Copyright 2009-2024 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2025 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 

package/src/sap/ui/core/History.js

@@ -1,6 +1,6 @@
 /*!
  * OpenUI5
- * (c) Copyright 2009-2024 SAP SE or an SAP affiliate company.
+ * (c) Copyright 2009-2025 SAP SE or an SAP affiliate company.
  * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
  */
 
@@ -22,7 +22,7 @@ sap.ui.define(['sap/ui/base/Object', "sap/ui/util/Storage"],
 	 *
 	 * @extends sap.ui.base.Object
 	 * @author SAP SE
-	 * @version 1.131.0
+	 * @version 1.132.0
 	 * @alias sap.ui.core.History
 	 * @protected
 	 */