@sapui5/types 1.118.1 → 1.119.1

package/types/sap.ushell.d.ts

@@ -1,4 +1,32 @@
-// For Library Version: 1.118.0
+// For Library Version: 1.119.2
+
+declare module "sap/ushell/library" {
+  /**
+   * Denotes the types of the content nodes.
+   */
+  export enum ContentNodeType {
+    /**
+     * A group of the classic homepage
+     */
+    HomepageGroup = "HomepageGroup",
+    /**
+     * A page which is assigned to a space in spaces mode
+     */
+    Page = "Page",
+    /**
+     * A space in spaces mode
+     */
+    Space = "Space",
+  }
+  /**
+   * The state of a navigation operation
+   */
+  export enum NavigationState {
+    Finished = "Finished",
+
+    InProgress = "InProgress",
+  }
+}
 
 declare module "sap/ushell/components/factsheet/controls/PictureTile" {
   import { default as CustomTile, $CustomTileSettings } from "sap/m/CustomTile";
@@ -1116,34 +1144,6 @@ declare module "sap/ushell/Container" {
   };
 }
 
-declare module "sap/ushell/library" {
-  /**
-   * Denotes the types of the content nodes.
-   */
-  export enum ContentNodeType {
-    /**
-     * A group of the classic homepage
-     */
-    HomepageGroup = "HomepageGroup",
-    /**
-     * A page which is assigned to a space in spaces mode
-     */
-    Page = "Page",
-    /**
-     * A space in spaces mode
-     */
-    Space = "Space",
-  }
-  /**
-   * The state of a navigation operation
-   */
-  export enum NavigationState {
-    Finished = "Finished",
-
-    InProgress = "InProgress",
-  }
-}
-
 declare module "sap/ushell/renderers/fiori2/Renderer" {
   import {
     default as UIComponent,
@@ -3155,7 +3155,7 @@ declare module "sap/ushell/services/CrossApplicationNavigation" {
      *
      * @returns A promise which resolves once the back navigation was triggered
      */
-    backToPreviousApp(): Promise<void>;
+    backToPreviousApp(): Promise<undefined>;
     /**
      * if sHashFragment is a compacted hash (sap-intent-param is present), in a hash, this function replaces
      * it into a long url with all parameters expanded
@@ -3522,7 +3522,7 @@ declare module "sap/ushell/services/CrossApplicationNavigation" {
       /**
        * positive integer representing the steps to go back in the history
        */
-      iSteps: number
+      iSteps: int
     ): void;
     /**
      * @since 1.15.0
@@ -4136,7 +4136,7 @@ declare module "sap/ushell/services/CrossApplicationNavigation" {
        * an optional UI5 component, used to logically attach a possibly generated app state.
        */
       oComponent?: object
-    ): Promise<void>;
+    ): Promise<undefined>;
   }
 }
 
@@ -4173,7 +4173,7 @@ declare module "sap/ushell/services/EndUserFeedback" {
      *
      * @returns Rejected promise
      */
-    isEnabled(): Object;
+    isEnabled(): object;
     /**
      * @since 1.25.1
      * @deprecated (since 1.93)
@@ -4493,7 +4493,11 @@ declare module "sap/ushell/services/LaunchPage" {
       /**
        * The catalog tile
        */
-      oCatalogTile: object
+      oCatalogTile: object,
+      /**
+       * SAP-internal: Whether the tile should be displayed in preview mode
+       */
+      bPreview?: boolean
     ): object;
     /**
      * Returns the UI5 view or control of a catalog tile
@@ -4504,7 +4508,11 @@ declare module "sap/ushell/services/LaunchPage" {
       /**
        * The catalog tile
        */
-      oCatalogTile: object
+      oCatalogTile: object,
+      /**
+       * SAP-internal: Whether the tile should be displayed in preview mode
+       */
+      bPreview?: boolean
     ): object;
     /**
      * Returns the catalog's title
@@ -4798,7 +4806,7 @@ declare module "sap/ushell/services/LaunchPage" {
       /**
        * A callback which returns an array of action objects.
        */
-      fnProvider: Object
+      fnProvider: object
     ): void;
     /**
      * Removes a group.
@@ -5030,6 +5038,458 @@ declare module "sap/ushell/services/Message" {
   }
 }
 
+declare module "sap/ushell/services/Navigation" {
+  import Component from "sap/ui/core/Component";
+
+  import { URI } from "sap/ui/core/library";
+
+  /**
+   * @since 1.119.0
+   *
+   * The Unified Shell's Navigation service allows to navigate to "external" targets outside of the currently
+   * running app (but still in scope of the current Fiori launchpad) or create links to such external targets.
+   *
+   * To use the Navigation service you can retrieve an instance via ushell's Container:
+   * ```javascript
+   *
+   *   sap.ui.require(["sap/ushell/Container"], async () => {
+   *     const oNavigationService = await Container.getServiceAsync("Navigation");
+   *     // Use the Navigation service
+   * ```
+   *
+   *
+   * The Navigation service currently provides platform independent functionality.
+   *
+   * The service is meant to be used by applications, plugins and shell components.
+   *
+   * Usage:
+   * ```javascript
+   *
+   *   sap.ui.require(["sap/ushell/Container"], async () => {
+   *     const oNavigationService = await Container.getServiceAsync("Navigation");
+   *     const sHref = await oNavigationService.getHref({
+   *       target : {
+   *         semanticObject: "Product",
+   *         action: "display"
+   *       },
+   *       params: {
+   *         "ProductID": "102343333"
+   *       }
+   *     }, oComponent);
+   *     // do something with the resolved sHref.
+   *   });
+   *   ```
+   *
+   *
+   * Parameter names and values are case sensitive.
+   *
+   * Note that the usage of multi-valued parameters (specifying an array with more than one member as parameter
+   * value, e.g. `params : { A : ["a1", "a2"] }`) is possible with this API but **strongly discouraged**.
+   * Depending on the used platform / back-end implementation the target matching might not support multi-value
+   * parameters. Furthermore, it is not guaranteed that additional parameter values specified in the back-end
+   * configuration are merged with parameter values passed via the Navigation service.
+   *
+   * Note that the application parameter length (including SemanticObject/Action) shall not exceed 512 bytes
+   * when serialized as UTF-8.
+   *
+   * Note that when receiving the values as startup parameters (as part of the component data object) single
+   * values are represented as an array of size 1. Above example is returned as ` deepEqual(getComponentData().startupParameters
+   * , { "ProductID" : [ "102343333" ] } ) `
+   *
+   * Make sure not to store sensitive data within an URL. URLs may appear in a server log, be persisted inside
+   * and outside the system.
+   *
+   * Note: When constructing large URLs, the URLs may be shortened and persisted on a database server for
+   * prolonged time, the actual data is persisted under a key accessible to any User (guessing the key).
+   *
+   * The same restrictions apply for the Application state.
+   */
+  export default class Navigation {
+    constructor();
+
+    /**
+     * @since 1.119.0
+     *
+     * Attempts to use the browser history to navigate to the previous app.
+     *
+     * A navigation to the Fiori launchpad Home is performed when this method is called on a first navigation.
+     * In all other cases, this function simply performs a browser back navigation.
+     *
+     * Please note that the behavior of this method is subject to change and therefore it may not yield to the
+     * expected results especially on mobile devices where "back" is the previous inner-app state if these are
+     * put into the history!
+     *
+     * @returns A promise which resolves once the back navigation was triggered
+     */
+    backToPreviousApp(): Promise<any>;
+    /**
+     * @since 1.119.0
+     *
+     * Returns a promise resolving to a URL that launches an app with certain parameters. This API can be used
+     * to convert the internal shell hash format into the URL format for use in link tags. The resulting href
+     * is fully encoded and cannot be used in other APIs expecting the internal decoded hash.
+     *
+     *
+     * ```javascript
+     *
+     *   sap.ui.require(["sap/ushell/Container"], async () => {
+     *     const oNavigationService = await Container.getServiceAsync("Navigation");
+     *     const sHref = await oNavigationService.getHref({
+     *       target: { shellHash: oLink.intent }
+     *     }, oComponent);
+     *     // do something with the resolved sHref.
+     *   });
+     * ```
+     *
+     *
+     * This API accepts a sap-xapp-state-data parameter that can be used generate a url that can be used to
+     * launch an app with certain data, for example:
+     * ```javascript
+     *
+     *   {
+     *     target : { semanticObject : "AnObject", action: "action" },
+     *     params : { "sap-xapp-state-data" : JSON.stringify({ a: "b", c: "d" }) }
+     *   }
+     * ```
+     *  Using the arguments as in the example above, a link with a sap-xapp-state parameter that encodes the
+     * provided data is returned. The sap-xapp-state-data parameter does not appear in the generated link.
+     *
+     * Do **not** use "#Shell-home" to navigate to a specific homepage! A proper way for an application to generate
+     * a link to return to the home page of the Fiori launchpad is: `getHref( { target : { shellHash : "#" }})`
+     *
+     * @returns A Promise resolving the encoded href.
+     */
+    getHref(
+      /**
+       * The navigation target to transform.
+       */
+      oTarget: Target,
+      /**
+       * A UI5 component, used to logically attach any related app state.
+       */
+      oComponent?: Component
+    ): Promise<string>;
+    /**
+     * @since 1.119.0
+     *
+     * Resolves the given filters to a list of links available to the user.
+     *
+     * @returns A promise that resolves an array with a list for each filter containing the matched links.
+     * **Note:** The intent is in a **internal** format and cannot be directly put into a link tag. If you want
+     * to use it directly you have to transform it first into a href.
+     * ```javascript
+     *
+     *         const sHref = await NavigationService.getHref({ target: { shellHash:  oLink.intent} }, oComponent);
+     *      ```
+     */
+    getLinks(
+      /**
+       * A list of target filters.
+       */
+      aLinkFilter?: LinkFilter[]
+    ): Promise<Link[][]>;
+    /**
+     * @since 1.119.0
+     *
+     * For a given semantic object, this method considers all actions associated with the semantic object and
+     * returns the one tagged as a "primaryAction". If no inbound tagged as "primaryAction" exists, then the
+     * intent of the first inbound (after sorting has been applied) matching the action "displayFactSheet".
+     *
+     * The primary intent is determined by querying {@link sap.ushell.services.Navigation#getLinks} with the
+     * given semantic object and optional parameter. Then the resulting list is filtered to the outcome that
+     * a single item remains.
+     *
+     * @returns A promise resolving a link matching the 'primaryAction' tag.
+     */
+    getPrimaryIntent(
+      /**
+       * The semantic object.
+       */
+      sSemanticObject: string,
+      /**
+       * A target filter.
+       */
+      oLinkFilter?: LinkFilter
+    ): Promise<Link>;
+    /**
+     * @since 1.119.0
+     *
+     * Returns a list of semantic objects of the intents the current user can navigate to.
+     *
+     * @returns A promise that resolves with an array of strings representing the semantic objects of the intents
+     * the current user can navigate to, or rejects with an error message. The returned array will not contain
+     * duplicates. **Note:** the caller should not rely on the specific order the semantic objects appear
+     * in the returned array.
+     */
+    getSemanticObjects(): Promise<string[]>;
+    /**
+     * @since 1.119.0
+     *
+     * Navigates back in history the number of given steps if this is supported by the underlying platform.
+     * If no argument is provided it will navigate back 1 step.
+     */
+    historyBack(
+      /**
+       * positive integer representing the steps to go back in the history
+       */
+      iSteps: int
+    ): void;
+    /**
+     * @since 1.119.0
+     *
+     * Checks whether the FLP has performed the first navigation. This method can be used to detect whether
+     * the current app was started directly, that is, without a previous navigation to another app, to the FLP
+     * home, or another target that adds an entry in the browser history.
+     *
+     * @returns This promise resolves with a boolean indicating if the current navigation is considered initial
+     */
+    isInitialNavigation(): Promise<boolean>;
+    /**
+     * @since 1.119.0
+     *
+     * Calculates whether the given navigation targets are supported for the given parameters, form factor etc.
+     * . "Supported" means that a valid navigation target is configured for the user and for the given device.
+     *
+     * `isNavigationSupported` is a test function for {@link sap.ushell.services.Navigation#navigate} and {@link sap.ushell.services.Navigation#getHref}.
+     *
+     * Example usage:
+     * ```javascript
+     *
+     *   const aResult = await oNavigationService.isNavigationSupported([{
+     *     target: { shellHash: "SalesOrder-approve?SOId=1234" }
+     *   }])
+     *   if (aResult[0].supported===true){
+     *       // enable link
+     *     }
+     *     else {
+     *       // disable link
+     *   }
+     * ```
+     */
+    isNavigationSupported(
+      /**
+       * A list of navigation targets to be checked.
+       */
+      aTargets: Target[],
+      /**
+       * The root component of the application.
+       */
+      oComponent?: Component
+    ): void;
+    /**
+     * @since 1.119.0
+     *
+     * Triggers a navigation to a specified target outside of the currently running application (e.g. different
+     * launchpad application). Invocation will trigger a hash change and subsequent invocation of the target.
+     *
+     * If the navigation target opens in a new window the running application may be retained.
+     *
+     * This API accepts a sap-xapp-state-data parameter that can be used generate a url that can be used to
+     * launch an app with certain data, for example:
+     * ```javascript
+     *
+     *   {
+     *     target : { semanticObject : "AnObject", action: "action" },
+     *     params : { "sap-xapp-state-data" : JSON.stringify({ a: "b", c: "d" }) }
+     *   }
+     * ```
+     *  Using the arguments as in the example above, a link with a sap-xapp-state parameter that encodes the
+     * provided data is returned. The sap-xapp-state-data parameter does not appear in the generated link.
+     *
+     * Do **not** use "#Shell-home" to navigate to a specific homepage! A proper way for an application to generate
+     * a link to return to the home page of the Fiori launchpad is: `navigate( { target : { shellHash : "#"
+     * }})`
+     *
+     * @returns A Promise resolving once the navigation was triggered. The Promise might never reject or resolve
+     * when an error occurs during the navigation.
+     */
+    navigate(
+      /**
+       * The navigation target.
+       */
+      oTarget: Target,
+      /**
+       * A UI5 component, used to logically attach any related app state.
+       */
+      oComponent?: Component
+    ): Promise<any>;
+    /**
+     * @since 1.119.0
+     * @ui5-protected Do not call from applications (only from related classes in the framework)
+     *
+     * Resolves the URL hash fragment. This function gets the hash part of the URL and returns the URL of the
+     * target application.
+     *
+     * @returns A Promise resolving the intent.
+     */
+    resolveIntent(
+      /**
+       * The formatted URL hash fragment in internal format (as obtained by the SAPUI5 hasher service) not as
+       * given in `location.hash`)! Example: `#SemanticObject-action?P1=V1&P2=A%20B%20C`
+       */
+      sHashFragment: string
+    ): Promise<{
+      url: string;
+    }>;
+  }
+  /**
+   * Optional properties may not be present in the link.
+   */
+  export type Link = {
+    /**
+     * The intent: for example "#AnObject-Action?A=B&C=e&C=j" **Note:** The intent is in a **internal** format
+     * and cannot be directly put into a link tag.
+     */
+    intent: string;
+    /**
+     * The title of the link.
+     */
+    text: string;
+    /**
+     * A URI to the icon: for example "sap-icon://Fiori2/F0018".
+     */
+    icon?: URI;
+    /**
+     * The short title of the link.
+     */
+    subTitle?: string;
+    /**
+     * The short title of the link.
+     */
+    shortTitle?: string;
+    /**
+     * The list of tags.
+     */
+    tags?: string[];
+  };
+
+  export type LinkFilter = {
+    /**
+     * Matches the semantic object of a link.
+     */
+    semanticObject?: string;
+    /**
+     * Matches the action object of a link.
+     */
+    action?: string;
+    /**
+     * Matches the parameters of a link.   **simple format:**
+     * ```javascript
+     *
+     *                                   {
+     *                                      P1: "B",
+     *                                      P2: ["e", "j"],
+     *                                   }
+     *                                   ```
+     *    **extended format:**
+     * ```javascript
+     *
+     *                                   {
+     *                                      P1: { value: "v1" },
+     *                                      P2: { value: ["v2", "v3"] }
+     *                                      P3: { value: "v4", required: true }
+     *                                   }
+     *                                   ```
+     *  `required`: Whether the parameter is be required (`true`) or not (`false`) in the signature of the matching
+     * target. Please note that this option is only effective on platforms using the `sap.ushell.services.ClientSideTargetResolution`
+     */
+    params?: object;
+    /**
+     * If `true`, matches only links that use at least one (non sap-) parameter from 'params'.
+     */
+    withAtLeastOneUsedParam?: boolean;
+    /**
+     * How the matching links should be sorted. Possible Values:
+     * 	 -  `"intent"` lexicographical sort on returned 'intent' field
+     * 	 -  `"text"` lexicographical sort on returned 'text' field
+     * 	 -  `"priority"` experimental - top intents are returned first
+     */
+    sortResultsBy?: string;
+    /**
+     * If true, only apps that match exactly the supplied technology (for example sap-ui-tech-hint=WDA) will
+     * be considered.
+     */
+    treatTechHintAsFilter?: boolean;
+    /**
+     * The UI5 component invoking the service, shall be a root component.
+     */
+    ui5Component: Component;
+    /**
+     * **SAP internal usage only** Application state key to add to the generated links.
+     */
+    appStateKey?: string;
+    /**
+     * Whether intents should be returned in compact format.
+     */
+    compactIntents?: boolean;
+    /**
+     * Matches only links which match an inbound with certain tags.
+     */
+    tags?: string[];
+  };
+
+  /**
+   * A target describing the intent: #-~?&/
+   * **Note:** The intent shall not exceed 512 bytes when serialized as UTF-8.
+   */
+  export type Target = {
+    /**
+     * Defaults to current hash. Please note that the only the `appSpecificRoute` will be considered when target
+     * is omitted.
+     */
+    target?: {
+      /**
+       * The semanticObject part of the intent.
+       */
+      semanticObject?: string;
+      /**
+       * The action part of the intent.
+       */
+      action?: string;
+      /**
+       * The contextRaw part of the intent without the '~' prefix.
+       */
+      contextRaw?: string;
+      /**
+       * The entire intent including parameters and appSpecificRoute. **Note:** If set all other parameters are
+       * ignored. **Note:** While parameters need to be url-encoded once when used in the `shellHash` the app
+       * specific route must not be encoded.
+       */
+      shellHash?: string;
+    };
+    /**
+     * The parameters of the target   **simple format:**
+     * ```javascript
+     *
+     *                                   {
+     *                                      P1: "B",
+     *                                      P2: ["e", "j"],
+     *                                   }
+     *                                   ```
+     *    **extended format:**
+     * ```javascript
+     *
+     *                                   {
+     *                                      P1: { value: "v1" },
+     *                                      P2: { value: ["v2", "v3"] }
+     *                                   }
+     *                                   ```
+     *    **Note:** Parameter values can contain special characters and must be provided unencoded.
+     * The APIs takes care of the necessary encodings.
+     */
+    params?: object;
+    /**
+     * The appSpecificRoute without the '&/' prefix.
+     */
+    appSpecificRoute?: string;
+    /**
+     * Wether the parameter provided in `params` should be applied or ignored. Parameters already set by the
+     * shellHash are ignored.
+     */
+    processParams?: boolean;
+  };
+}
+
 declare module "sap/ushell/services/NavTargetResolution" {
   /**
    * @since 1.15.0
@@ -5070,8 +5530,8 @@ declare module "sap/ushell/services/NavTargetResolution" {
      * Tells whether the given navigation intent(s) are supported for the given parameters Supported" means
      * that a valid navigation target is configured for the user for the given device form factor.
      *
-     * This is effectively a test function for {@link toExternal}/ {@link hrefForExternal}. It is functionally
-     * equivalent to {@link isIntentSupported} but accepts the same input as {@link toExternal}/ {@link hrefForExternal}.
+     * This is effectively a test function for {@link toExternal}/ {@link hrefForExternal}. It function accepts
+     * the same input as {@link toExternal}/ {@link hrefForExternal}.
      *
      * @returns A `jQuery.Deferred` object's promise which is resolved with an array (!) of objects representing
      * whether the intent is supported or not objects with a property `supported` of type `boolean`.
@@ -5323,7 +5783,7 @@ declare module "sap/ushell/services/Notifications" {
      *
      * @returns Returns the number of notifications of the user
      */
-    getNotificationsCount(): number;
+    getNotificationsCount(): int;
     /**
      * @since 1.44
      *
@@ -5635,9 +6095,9 @@ declare module "sap/ushell/services/Personalization" {
      *
      * Note: the underlying storage model for Objects stored with getContainer / getPersonalizationContainer
      * is identical.
-     *  Thus you can safely migrate your client implementation from the deprecated getContainer to getPersonalizationContainer
-     * without loss of data. One may even run mixed set of applications on the same container keys. The sole
-     * differences are w.r.t. client side handling of the Context data within one session.
+     *  Thus you can safely migrate your client implementation from the deprecated `getPersonalizationContainer`
+     * to `getContainer` without loss of data. One may even run mixed set of applications on the same container
+     * keys. The sole differences are w.r.t. client side handling of the Context data within one session.
      *
      * If you want to use the variant interface, use the following pattern
      * ```javascript
@@ -9443,7 +9903,69 @@ declare module "sap/ushell/ui5service/UserStatus" {
 }
 
 declare namespace sap {
+  /**
+   * @since 1.15.0
+   *
+   * SAP library: sap.ushell
+   */
   namespace ushell {
+    /**
+     * @since 1.15.0
+     *
+     * Initializes the Unified Shell Container.
+     *
+     * This platform-specific method must be called exactly once in the very beginning to resolve all necessary
+     * dependencies and prepare Unified Shell's global infrastructure. As soon as the returned promise has been
+     * resolved, the container will be available as a singleton object in namespace `sap.ushell.Container`.
+     *
+     * **Note:** `sap.ushell.bootstrap` is used internally by the SAP Fiori launchpad. Developers who build
+     * apps or plugins for the SAP Fiori launchpad should use `sap.ushell.bootstrap` in their code. However,
+     * there are special use cases where a customized bootstrap of Unified Shell is helpful, e.g. when Unified
+     * Shell UI services need to be accessed without having loaded the Unified Shell's UI. In such cases, additional
+     * dependencies need to be required to allow proper usage of the Unified Shell's functionality.
+     *
+     * **Example:**
+     * ```javascript
+     *
+     * <script id="sap-ui-bootstrap"
+     *         src=".../sap-ui-core.js"
+     *         data-sap-ui-libs="sap.ushell, sap.m">
+     * </script>
+     *
+     * <!--...-->
+     *
+     * <script>
+     *   sap.ui.getCore().attachInit(function () {
+     *   // Container needs to be required to make sap.ushell.bootstrap available
+     *     sap.ui.require(["sap/ushell/Container", ... ], function (Container) {
+     *       window["sap-ushell-config"] = {...};
+     *
+     *       sap.ushell.bootstrap("abap", {
+     *         abap: "sap.ushell_abap.adapters.abap"
+     *       }).then(function () {
+     *         sap.ushell.Container.getServiceAsync(\/* Service *\/).then(function (serviceInstance) {
+     *           ...
+     *         });
+     *       });
+     *     });
+     *   });
+     * </script>
+     * ```
+     *
+     *
+     * @returns a promise that is resolved once the container is available
+     */
+    function bootstrap(
+      /**
+       * the target platform, such as "abap" or "cdm".
+       */
+      sPlatform: string,
+      /**
+       * the map with platform specific package names for the service adapters. You only need to specify these
+       * package names if they differ from the standard name `"sap.ushell.adapters." + sPlatform`.
+       */
+      mAdapterPackagesByPlatform?: Record<string, string>
+    ): jQuery.Promise;
     /**
      * @since 1.15.0
      *
@@ -10483,6 +11005,8 @@ declare namespace sap {
 
     "sap/ushell/services/Message": undefined;
 
+    "sap/ushell/services/Navigation": undefined;
+
     "sap/ushell/services/NavTargetResolution": undefined;
 
     "sap/ushell/services/Notifications": undefined;