@sapui5/ts-types 1.150.1 → 1.151.0

package/types/sap.ui.joule.frontend.d.ts

@@ -0,0 +1,710 @@
+// For Library Version: 1.151.0
+
+declare namespace sap {
+  namespace ui {
+    namespace joule {
+      /**
+       * UI5 library for integrating frontend actions with SAP Joule.
+       *
+       * This library provides a unified API for registering frontend actions with SAP Joule, automatically handling
+       * both FLP (MessageBroker) and standalone communication modes.
+       *
+       * Generic actions (describeUI, describeUIElement, setFields, executeAction) are registered automatically
+       * at library load time. Applications only need to create a JouleConnector if they have app-specific custom
+       * actions to register.
+       *
+       * @experimental As of version 1.151.
+       */
+      namespace frontend {
+        /**
+         * Channel version used for MessageBroker communication.
+         *
+         * @experimental As of version 1.151.
+         */
+        export const CHANNEL_VERSION: string;
+
+        namespace util {
+          /**
+           * Helper utilities for implementing frontend actions with Joule. These functions provide reusable implementations
+           * of common frontend action patterns, allowing applications to easily expose UI introspection and manipulation
+           * capabilities to Joule without implementing the underlying logic themselves.
+           *
+           * The describeUI and describeUIElement methods automatically enrich UI elements with jouleControlEnrichment
+           * metadata from control designtime files when available. This allows controls/libraries to provide Joule-specific
+           * metadata (e.g., column names for SmartTable).
+           *
+           * @experimental As of version 1.151.
+           */
+          interface ActionHelpers {
+            /**
+             * Describes the UI by returning a hierarchical tree representation of visible UI elements.
+             *
+             * This function provides a structured view of the UI with simplified control types and hierarchical nesting
+             * (containers have their children nested, select controls have their options as children, etc.). This is
+             * useful for Joule to understand the UI structure and relationships between elements.
+             *
+             * Automatically enriches elements with jouleControlEnrichment from designtime metadata when available.
+             * Smart controls (SmartTable, SmartChart, SmartFilterBar) and their inner controls are properly captured
+             * in the hierarchy.
+             *
+             * Response structure:
+             * ```javascript
+             *
+             * [
+             *   {
+             *     id: String,             // Unique control ID
+             *     label: String,          // Human-readable label
+             *     type: String,           // Simplified type (e.g., "smartTable", "input", "button", "form")
+             *     description: String,    // Optional description/tooltip
+             *     value: any,             // Current value of the control
+             *     editable: boolean,      // Whether the control is editable
+             *     valueTypeHint: String,  // Type hint (String, Integer, Float, Boolean, Date, Object)
+             *     jouleControlEnrichment: Object,   // Optional jouleControlEnrichment from designtime metadata
+             *     children: Array         // Nested child elements
+             *   }
+             * ]
+             * ```
+             *
+             *
+             * Container types (form, panel, page, smartTable) will have their child controls nested in children. Group
+             * controls (selectGroup) will have selectOption children. Select controls will have selectOption children
+             * for their items.
+             *
+             *
+             * @returns Promise resolving to hierarchical array of UI elements
+             */
+            describeUI(
+              /**
+               * Root control to start scanning from, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Optional parameters (only when first param is root control)
+               */
+              oParams?: {
+                /**
+                 * Start ID of the tree. When provided, the control with this ID is used as root (only its descendants are
+                 * returned).
+                 */
+                rootElementId?: string;
+                /**
+                 * Properties to include in response elements. Uses SAP GUI naming convention (mapped internally). When
+                 * omitted, all properties are included.
+                 */
+                includedProperties?: string[];
+                /**
+                 * Simplified type names of controls to exclude from the response (e.g., "Table", "SmartTable", "Toolbar").
+                 * Case-insensitive. When omitted, nothing is excluded.
+                 */
+                excludedElementTypes?: string[];
+              }
+            ): Promise<any[]>;
+            /**
+             * Describes a specific UI element by its control ID.
+             *
+             * This function locates a control by its ID and returns a detailed description of that specific control
+             * with its children (if any). The description includes simplified types, labels, values, and hierarchical
+             * children.
+             *
+             * Automatically enriches elements with jouleControlEnrichment from designtime metadata when available.
+             *
+             * Response structure (on success):
+             * ```javascript
+             *
+             * {
+             *   id: String,             // Unique control ID
+             *   label: String,          // Human-readable label
+             *   type: String,           // Simplified type (e.g., "smartTable", "input", "button")
+             *   description: String,    // Optional description/tooltip
+             *   value: any,             // Current value of the control
+             *   editable: boolean,      // Whether the control is editable
+             *   valueTypeHint: String,  // Type hint (String, Integer, Float, Boolean, Date, Object)
+             *   jouleControlEnrichment: Object,   // Optional jouleControlEnrichment from designtime metadata
+             *   children: Array         // Nested child elements
+             * }
+             * ```
+             *
+             *
+             * Response structure (on error):
+             * ```javascript
+             *
+             * {
+             *   success: false,
+             *   error: String           // Error message
+             * }
+             * ```
+             *
+             *
+             *
+             * @returns Promise resolving to UiElement object on success or error object on failure
+             */
+            describeUIElement(
+              /**
+               * Root control for validation, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Parameters (only when first param is root control)
+               */
+              oParams?: {
+                /**
+                 * Control ID to describe
+                 */
+                elementId: string;
+              }
+            ): Promise<object>;
+            /**
+             * Executes a named action on a control (e.g., press a button, select an item).
+             *
+             * This function locates a control by its ID and triggers the action specified by actionName. Supported
+             * action names: - "press" - firePress() for buttons, links, menu items, tiles - "select" - fireSelect()
+             * for selectable controls - "tap" - fireTap() for legacy controls - "toggle" - toggles selected state for
+             * checkboxes/switches - "expand" - expands a collapsible control - "collapse" - collapses an expandable
+             * control
+             *
+             *
+             * @returns Result object with success/error
+             */
+            executeAction(
+              /**
+               * Root control for validation, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Parameters (only when first param is root control)
+               */
+              oParams?: {
+                /**
+                 * Control ID to execute action on
+                 */
+                elementId: string;
+                /**
+                 * Name of the action to execute (e.g., "press", "select", "tap")
+                 */
+                actionName: string;
+                /**
+                 * Optional parameters to pass to the action event
+                 */
+                actionParameters?: object;
+              }
+            ): object;
+            /**
+             * Gets all visible UI elements from the application in a flat array.
+             *
+             * This function traverses the UI control tree starting from the specified root control and returns an array
+             * of all visible UI elements with their metadata (ID, type, value, etc.). Applications can use this in
+             * their frontend actions to expose their UI structure to Joule.
+             *
+             * Note: This method returns a flat list and does not include jouleControlEnrichment enrichment. Use describeUI()
+             * for hierarchical structure with jouleControlEnrichment support.
+             *
+             * Response structure:
+             * ```javascript
+             *
+             * [
+             *   {
+             *     fieldName: String,      // Unique control ID
+             *     type: String,           // Full control type (e.g., "sap.m.Input")
+             *     description: String,    // Human-readable description (from label, placeholder, or tooltip)
+             *     fieldValue: any,        // Current value of the control
+             *     valueType: String,      // Type of the value (String, Integer, Float, Boolean, Date, Object)
+             *     children: Array         // Child elements (currently empty, reserved for future use)
+             *   }
+             * ]
+             * ```
+             *
+             *
+             *
+             * @returns Array of UI elements
+             */
+            getFields(
+              /**
+               * Root control to start scanning from, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Optional parameters (only when first param is root control)
+               */
+              oParams?: object
+            ): any[];
+            /**
+             * Sets a field value by finding the control and updating it.
+             *
+             * This function locates a control by its ID or label and sets its value. For model-bound controls (like
+             * SmartField), it updates the underlying model binding directly. It also fires change events to notify
+             * listeners of the value change.
+             *
+             *
+             * @returns Result object with success/error
+             */
+            setField(
+              /**
+               * Root control for searching, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Parameters (only when first param is root control)
+               */
+              oParams?: {
+                /**
+                 * Control ID or label text to find
+                 */
+                fieldName: string;
+                /**
+                 * Value to set
+                 */
+                fieldValue: any;
+              }
+            ): object;
+            /**
+             * Sets multiple field values in a single call.
+             *
+             * This function provides a batch operation for setting multiple field values at once. It iterates through
+             * each field in the provided array and attempts to set its value using the setField method. Results are
+             * aggregated and returned with detailed information about each field's success or failure.
+             *
+             * The fields array uses variable-key dict format where each object has a single key (the field ID) mapped
+             * to its value: [{"fieldId": "fieldValue"}, ...]
+             *
+             *
+             * @returns Result object with success/error and detailed results
+             */
+            setFields(
+              /**
+               * Root control for searching, or params object if no root control
+               */
+              oRootControlOrParams?: sap.ui.core.Control | object,
+              /**
+               * Parameters (only when first param is root control)
+               */
+              oParams?: {
+                /**
+                 * Array of single-key objects where key is field ID and value is the field value
+                 */
+                fields: object[];
+              }
+            ): object;
+          }
+        }
+        /**
+         * Factory module for creating generic frontend action definitions.
+         *
+         * This module provides a set of standard UI introspection actions that are automatically included by JouleConnector.
+         * These actions use ActionHelpers to provide consistent UI scanning and manipulation capabilities.
+         *
+         * All actions return a standardized response envelope:
+         * ```javascript
+         *
+         * {
+         *   status: "success"|"error",   // Overall status
+         *   content: any                 // Raw data or {success, error/message} object
+         * }
+         * ```
+         *
+         *
+         * @experimental As of version 1.151.
+         */
+        interface GenericActions {
+          /**
+           * Creates an array of generic frontend action definitions.
+           *
+           * The following actions are created: - com.sap.ui.unified.frontend.actions.describeUI - Describes UI as
+           * a hierarchical tree - com.sap.ui.unified.frontend.actions.describeUIElement - Describes a specific UI
+           * element by ID - com.sap.ui.unified.frontend.actions.setFields - Sets multiple field values in a single
+           * call - com.sap.ui.unified.frontend.actions.executeAction - Executes an action on a control (e.g., press
+           * a button)
+           *
+           *
+           * @returns Array of frontend action definitions.
+           */
+          create(): object[];
+        }
+
+        /**
+         * Class to facilitate communication between Applications and SAP Joule via SAP Fiori Launchpad for registering
+         * frontend actions.
+         *
+         * Use this class when running in FLP environment. For a unified API that works in both FLP and standalone
+         * environments, use {@link sap.ui.joule.frontend.JouleConnector} instead.
+         *
+         * @experimental As of version 1.151.
+         */
+        class FLPJouleBridge extends sap.ui.base.Object {
+          /**
+           * Constructor for FLPJouleBridge.
+           */
+          constructor(
+            /**
+             * The client ID to be used when connecting to the FLP MessageBroker. Must be unique across applications.
+             */
+            sClientId: string
+          );
+
+          /**
+           * Creates a new subclass of class sap.ui.joule.frontend.FLPJouleBridge with name `sClassName` and enriches
+           * it with the information contained in `oClassInfo`.
+           *
+           * `oClassInfo` might contain the same kind of information as described in {@link sap.ui.base.Object.extend}.
+           *
+           *
+           * @returns Created class / constructor function
+           */
+          static extend<T extends Record<string, unknown>>(
+            /**
+             * Name of the class being created
+             */
+            sClassName: string,
+            /**
+             * Object literal with information about the class
+             */
+            oClassInfo?: sap.ClassInfo<T, sap.ui.joule.frontend.FLPJouleBridge>,
+            /**
+             * Constructor function for the metadata object; if not given, it defaults to the metadata implementation
+             * used by this class
+             */
+            FNMetaImpl?: Function
+          ): Function;
+          /**
+           * Returns a metadata object for class sap.ui.joule.frontend.FLPJouleBridge.
+           *
+           *
+           * @returns Metadata object describing this class
+           */
+          static getMetadata(): sap.ui.base.Metadata;
+          /**
+           * Disconnects the FLPJouleBridge from the MessageBroker and unsubscribes from all channels. Must be called
+           * to clean up resources when the bridge is no longer needed. It cannot be re-connected later.
+           *
+           *
+           * @returns A Promise that resolves when the bridge has been disconnected.
+           */
+          disconnect(): Promise<void>;
+          /**
+           * Returns the client ID used by this bridge.
+           *
+           *
+           * @returns The client ID.
+           */
+          getClientId(): string;
+          /**
+           * Checks if the bridge is currently connected.
+           *
+           *
+           * @returns True if connected, false otherwise.
+           */
+          isConnected(): boolean;
+          /**
+           * Registers callback functions to handle frontend action requests from Joule.
+           *
+           *
+           * @returns A Promise that resolves when the callback has been registered.
+           */
+          register(
+            /**
+             * An object containing callback functions for Joule frontend actions.
+             */
+            oJouleCallbacks: {
+              /**
+               * Callback that returns an array of frontend actions.
+               */
+              getFrontendActions: Function;
+            }
+          ): Promise<void>;
+        }
+        /**
+         * Unified connector for SAP Joule frontend action integration.
+         *
+         * This is the main entry point for integrating frontend actions with SAP Joule. It automatically detects
+         * the runtime environment (FLP or standalone) and uses the appropriate communication mechanism.
+         *
+         * @experimental As of version 1.151.
+         */
+        class JouleConnector extends sap.ui.base.Object {
+          /**
+           * Constructor for JouleConnector.
+           */
+          constructor(
+            /**
+             * A unique client ID for this application's registration with Joule. This ID must be unique across all
+             * applications.
+             */
+            sClientId: string,
+            /**
+             * Optional configuration options.
+             */
+            oOptions?: {
+              /**
+               * Whether to auto-detect the environment. If false, you must call registerActions() manually.
+               */
+              autoDetect?: boolean;
+            }
+          );
+
+          /**
+           * Creates a new subclass of class sap.ui.joule.frontend.JouleConnector with name `sClassName` and enriches
+           * it with the information contained in `oClassInfo`.
+           *
+           * `oClassInfo` might contain the same kind of information as described in {@link sap.ui.base.Object.extend}.
+           *
+           *
+           * @returns Created class / constructor function
+           */
+          static extend<T extends Record<string, unknown>>(
+            /**
+             * Name of the class being created
+             */
+            sClassName: string,
+            /**
+             * Object literal with information about the class
+             */
+            oClassInfo?: sap.ClassInfo<T, sap.ui.joule.frontend.JouleConnector>,
+            /**
+             * Constructor function for the metadata object; if not given, it defaults to the metadata implementation
+             * used by this class
+             */
+            FNMetaImpl?: Function
+          ): Function;
+          /**
+           * Returns a metadata object for class sap.ui.joule.frontend.JouleConnector.
+           *
+           *
+           * @returns Metadata object describing this class
+           */
+          static getMetadata(): sap.ui.base.Metadata;
+          /**
+           * Disconnects from Joule and cleans up resources.
+           *
+           * Should be called when the application is exiting (e.g., in onExit lifecycle method).
+           *
+           *
+           * @returns A Promise that resolves when disconnection is complete.
+           */
+          disconnect(): Promise<void>;
+          /**
+           * Returns the client ID used by this connector.
+           *
+           *
+           * @returns The client ID.
+           */
+          getClientId(): string;
+          /**
+           * Returns the detected environment type.
+           *
+           *
+           * @returns The environment type (FLP or STANDALONE).
+           */
+          getEnvironmentType(): sap.ui.joule.frontend.EnvironmentType;
+          /**
+           * Checks if the connector is currently connected to Joule.
+           *
+           *
+           * @returns True if connected, false otherwise.
+           */
+          isConnected(): boolean;
+          /**
+           * Checks if running in FLP environment.
+           *
+           *
+           * @returns True if in FLP, false otherwise.
+           */
+          isFLP(): boolean;
+          /**
+           * Checks if running in standalone mode.
+           *
+           *
+           * @returns True if standalone, false otherwise.
+           */
+          isStandalone(): boolean;
+          /**
+           * Registers app-specific frontend actions with Joule.
+           *
+           * Generic UI actions (describeUI, describeUIElement, setFields, executeAction) are automatically registered
+           * at library load time under a separate client ID. This method registers app-specific actions independently
+           * under the app's own client ID.
+           *
+           *
+           * @returns This instance for chaining.
+           */
+          registerActions(
+            /**
+             * A function that returns an array of app-specific frontend action definitions. This function is called
+             * by Joule for each user prompt to get the available actions.
+             */
+            fnGetActions?: Function
+          ): sap.ui.joule.frontend.JouleConnector;
+          /**
+           * Registers an additional callback with Joule beyond frontend actions.
+           *
+           * Use this method to register callbacks for lifecycle events, context changes, chat events, or other Joule
+           * webclient interactions that are not frontend actions.
+           *
+           * Can be called before or after {@link #registerActions}. If called after, the callback is added to the
+           * already-connected bridge immediately.
+           *
+           *
+           * @returns This instance for chaining.
+           */
+          registerCallback(
+            /**
+             * The callback name (e.g., "onContextChange", "onChatEvent"). Must not be "getFrontendActions" — use registerActions()
+             * for that.
+             */
+            sName: string,
+            /**
+             * The callback handler function.
+             */
+            fnHandler: Function
+          ): sap.ui.joule.frontend.JouleConnector;
+        }
+        /**
+         * Connector for standalone (non-FLP) Joule integration.
+         *
+         * This class handles direct communication with the Joule webclient API when running outside of SAP Fiori
+         * Launchpad. It supports both immediate registration (when Joule is already loaded) and pre-registration
+         * (when Joule loads later).
+         *
+         * For a unified API that works in both FLP and standalone environments, use {@link sap.ui.joule.frontend.JouleConnector }
+         * instead.
+         *
+         * @experimental As of version 1.151.
+         */
+        class StandaloneConnector extends sap.ui.base.Object {
+          /**
+           * Constructor for StandaloneConnector.
+           */
+          constructor(
+            /**
+             * The unique client ID for registration with Joule.
+             */
+            sClientId: string
+          );
+
+          /**
+           * Creates a new subclass of class sap.ui.joule.frontend.StandaloneConnector with name `sClassName` and
+           * enriches it with the information contained in `oClassInfo`.
+           *
+           * `oClassInfo` might contain the same kind of information as described in {@link sap.ui.base.Object.extend}.
+           *
+           *
+           * @returns Created class / constructor function
+           */
+          static extend<T extends Record<string, unknown>>(
+            /**
+             * Name of the class being created
+             */
+            sClassName: string,
+            /**
+             * Object literal with information about the class
+             */
+            oClassInfo?: sap.ClassInfo<
+              T,
+              sap.ui.joule.frontend.StandaloneConnector
+            >,
+            /**
+             * Constructor function for the metadata object; if not given, it defaults to the metadata implementation
+             * used by this class
+             */
+            FNMetaImpl?: Function
+          ): Function;
+          /**
+           * Returns a metadata object for class sap.ui.joule.frontend.StandaloneConnector.
+           *
+           *
+           * @returns Metadata object describing this class
+           */
+          static getMetadata(): sap.ui.base.Metadata;
+          /**
+           * Disconnects from the Joule webclient and cleans up resources.
+           *
+           * @experimental As of version 1.151.
+           */
+          disconnect(): void;
+          /**
+           * Returns the client ID used by this connector.
+           *
+           * @experimental As of version 1.151.
+           *
+           * @returns The client ID.
+           */
+          getClientId(): string;
+          /**
+           * Checks if the connector is currently registered or pre-registered.
+           *
+           * @experimental As of version 1.151.
+           *
+           * @returns True if registered or pre-registered, false otherwise.
+           */
+          isConnected(): boolean;
+          /**
+           * Checks if direct registration was used (vs pre-registration).
+           *
+           *
+           * @returns True if directly registered, false if pre-registered.
+           */
+          isDirectlyRegistered(): boolean;
+          /**
+           * Registers callbacks with the Joule webclient.
+           *
+           * If the Joule webclient is already loaded, registration happens immediately. Otherwise, the callbacks
+           * are stored for pre-registration and will be picked up when the Joule webclient loads.
+           *
+           * @experimental As of version 1.151.
+           */
+          register(
+            /**
+             * An object containing callback functions for Joule frontend actions.
+             */
+            oJouleCallbacks: {
+              /**
+               * Callback that returns an array of frontend actions.
+               */
+              getFrontendActions: Function;
+            }
+          ): void;
+        }
+        /**
+         * Environment types for Joule integration.
+         *
+         * This enum is part of the 'sap/ui/joule/frontend/library' module export and must be accessed by the property
+         * 'EnvironmentType'.
+         *
+         * @experimental As of version 1.151.
+         */
+        enum EnvironmentType {
+          /**
+           * Running inside SAP Fiori Launchpad (FLP). Communication with Joule uses the FLP MessageBroker.
+           */
+          FLP = "undefined",
+          /**
+           * Running as a standalone application. Communication with Joule uses the direct webclient API.
+           */
+          STANDALONE = "undefined",
+        }
+        /**
+         * Message names used in Joule FLP MessageBroker communication. These values are protocol-specific and must
+         * match what Joule expects.
+         *
+         * This enum is part of the 'sap/ui/joule/frontend/library' module export and must be accessed by the property
+         * 'MessageName'.
+         *
+         * @experimental As of version 1.151.
+         */
+        enum MessageName {}
+      }
+    }
+  }
+
+  interface IUI5DefineDependencyNames {
+    "sap/ui/joule/frontend/FLPJouleBridge": undefined;
+
+    "sap/ui/joule/frontend/GenericActions": undefined;
+
+    "sap/ui/joule/frontend/JouleConnector": undefined;
+
+    "sap/ui/joule/frontend/library": undefined;
+
+    "sap/ui/joule/frontend/StandaloneConnector": undefined;
+
+    "sap/ui/joule/frontend/util/ActionHelpers": undefined;
+  }
+}