@microsoft/teams-js 2.31.0-beta.1 → 2.31.0

package/dist/esm/packages/teams-js/dts/public/pages.d.ts

@@ -1,574 +0,0 @@
-import { AppId } from '../public/appId';
-import { FrameInfo, ShareDeepLinkParameters, TabInformation, TabInstance, TabInstanceParameters } from './interfaces';
-export declare function navigateCrossDomainHelper(apiVersionTag: string, url: string): Promise<void>;
-export declare function backStackNavigateBackHelper(apiVersionTag: string): Promise<void>;
-export declare function tabsNavigateToTabHelper(apiVersionTag: string, tabInstance: TabInstance): Promise<void>;
-/**
- * @hidden
- */
-export declare function returnFocusHelper(apiVersionTag: string, navigateForward?: boolean): void;
-export declare function getTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
-export declare function getMruTabInstancesHelper(apiVersionTag: string, tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
-export declare function shareDeepLinkHelper(apiVersionTag: string, deepLinkParameters: ShareDeepLinkParameters): void;
-export declare function setCurrentFrameHelper(apiVersionTag: string, frameInfo: FrameInfo): void;
-export declare function configSetValidityStateHelper(apiVersionTag: string, validityState: boolean): void;
-export declare function getConfigHelper(apiVersionTag: string): Promise<pages.InstanceConfig>;
-export declare function configSetConfigHelper(apiVersionTag: string, instanceConfig: pages.InstanceConfig): Promise<void>;
-/**
- * Navigation-specific part of the SDK.
- */
-export declare namespace pages {
-    /** Callback function */
-    type handlerFunctionType = () => void;
-    /** Full screen function */
-    type fullScreenChangeFunctionType = (isFullScreen: boolean) => void;
-    /** Back button handler function */
-    type backButtonHandlerFunctionType = () => boolean;
-    /** Save event function */
-    type saveEventType = (evt: pages.config.SaveEvent) => void;
-    /** Remove event function */
-    type removeEventType = (evt: pages.config.RemoveEvent) => void;
-    /**
-     * @hidden
-     * List of enter focus action items
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    enum EnterFocusType {
-        /**
-         * Determines the previous direction to focus in app when hot keys entered.
-         */
-        PreviousLandmark = 0,
-        /**
-         * Determines the next direction to focus in app when hot keys entered.
-         */
-        NextLandmark = 1,
-        /**
-         * Determines if the focus should go to the particular content of the app.
-         * Read - Focus should go to the content of the app.
-         */
-        Read = 2,
-        /**
-         * Determines if the focus should go to the particular content of the app.
-         * Compose - Focus should go to the compose area (such as textbox) of the app.
-         */
-        Compose = 3
-    }
-    /**
-     * Return focus action items
-     */
-    enum ReturnFocusType {
-        /**
-         * Determines the direction to focus in host for previous landmark.
-         */
-        PreviousLandmark = 0,
-        /**
-         * Determines the direction to focus in host for next landmark.
-         */
-        NextLandmark = 1,
-        /**
-         * Determines if the focus should go to the host's activity feed
-         */
-        GoToActivityFeed = 2
-    }
-    /**
-     * @deprecated
-     * Return focus to the host. Will move focus forward or backward based on where the application container falls in
-     * the F6/tab order in the host.
-     * On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no
-     * effect and will be a no-op when called.
-     * @param navigateForward - Determines the direction to focus in host.
-     */
-    function returnFocus(navigateForward?: boolean): void;
-    /**
-     * Return focus to the host. Will attempt to send focus to the appropriate part of the host (as specified by returnFocusType) based on where the application container falls in
-     * the F6/tab order in the host.
-     * On mobile hosts or hosts where there is no keyboard interaction or UI notion of "focus" this function has no
-     * effect and will be a no-op when called.
-     * @param returnFocusType - Determines the type of focus to return to in the host.
-     */
-    function returnFocus(returnFocusType: pages.ReturnFocusType): void;
-    /**
-     * @hidden
-     *
-     * Registers a handler for specifying focus when it passes from the host to the application.
-     * On mobile hosts or hosts where there is no UI notion of "focus" the handler registered with
-     * this function will never be called.
-     *
-     * @param handler - The handler for placing focus within the application.
-     *
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    function registerFocusEnterHandler(handler: (navigateForward: boolean, enterFocusType?: EnterFocusType) => void): void;
-    /**
-     * Sets/Updates the current frame with new information
-     *
-     * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
-     * user clicks 'Go To Website'
-     */
-    function setCurrentFrame(frameInfo: FrameInfo): void;
-    /**
-     * Initializes the library with context information for the frame
-     *
-     * @param frameInfo - Frame information containing the URL used in the iframe on reload and the URL for when the
-     *  user clicks 'Go To Website'
-     * @param callback - An optional callback that is executed once the application has finished initialization.
-     * @param validMessageOrigins - An optional list of cross-frame message origins. They must have
-     * https: protocol otherwise they will be ignored. Example: https:www.example.com
-     */
-    function initializeWithFrameContext(frameInfo: FrameInfo, callback?: handlerFunctionType, validMessageOrigins?: string[]): void;
-    /**
-     * Defines the configuration of the current or desired instance
-     */
-    interface InstanceConfig {
-        /**
-         * A suggested display name for the new content.
-         * In the settings for an existing instance being updated, this call has no effect.
-         */
-        suggestedDisplayName?: string;
-        /**
-         * Sets the URL to use for the content of this instance.
-         */
-        contentUrl: string;
-        /**
-         * Sets the URL for the removal configuration experience.
-         */
-        removeUrl?: string;
-        /**
-         * Sets the URL to use for the external link to view the underlying resource in a browser.
-         */
-        websiteUrl?: string;
-        /**
-         * The developer-defined unique ID for the entity to which this content points.
-         */
-        entityId?: string;
-    }
-    /**
-     * Gets the config for the current instance.
-     * @returns Promise that resolves with the {@link InstanceConfig} object.
-     */
-    function getConfig(): Promise<InstanceConfig>;
-    /**
-     * @deprecated
-     * As of 2.0.0, this API is deprecated and can be replaced by the standard JavaScript
-     * API, window.location.href, when navigating the app to a new cross-domain URL. Any URL
-     * that is redirected to must be listed in the validDomains block of the manifest. Please
-     * remove any calls to this API.
-     * @param url - The URL to navigate the frame to.
-     * @returns Promise that resolves when the navigation has completed.
-     */
-    function navigateCrossDomain(url: string): Promise<void>;
-    /**
-     * Used to navigate to apps other than your own.
-     *
-     * If you are looking to navigate within your own app, use {@link pages.currentApp.navigateToDefaultPage} or {@link pages.currentApp.navigateTo}
-     *
-     * @param params Parameters for the navigation
-     * @returns a `Promise` that will resolve if the navigation was successful or reject if it was not
-     * @throws `Error` if the app ID is not valid or `params.webUrl` is defined but not a valid URL
-     */
-    function navigateToApp(params: AppNavigationParameters | NavigateToAppParams): Promise<void>;
-    /**
-     * Shares a deep link that a user can use to navigate back to a specific state in this page.
-     * Please note that this method does not yet work on mobile hosts.
-     *
-     * @param deepLinkParameters - ID and label for the link and fallback URL.
-     */
-    function shareDeepLink(deepLinkParameters: ShareDeepLinkParameters): void;
-    /**
-     * Registers a handler for changes from or to full-screen view for a tab.
-     * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-     * On hosts where there is no support for making an app full screen, the handler registered
-     * with this function will never be called.
-     * @param handler - The handler to invoke when the user toggles full-screen view for a tab.
-     */
-    function registerFullScreenHandler(handler: fullScreenChangeFunctionType): void;
-    /**
-     * Checks if the pages capability is supported by the host
-     * @returns boolean to represent whether the appEntity capability is supported
-     *
-     * @throws Error if {@linkcode app.initialize} has not successfully completed
-     */
-    function isSupported(): boolean;
-    /**
-     * @deprecated
-     * This interface has been deprecated in favor of a more type-safe interface using {@link pages.AppNavigationParameters}
-     *
-     * Parameters for the {@link pages.navigateToApp} function
-     */
-    interface NavigateToAppParams {
-        /**
-         * ID of the app to navigate to
-         */
-        appId: string;
-        /**
-         * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
-         */
-        pageId: string;
-        /**
-         * Fallback URL to open if the navigation cannot be completed within the host (e.g. if the target app is not installed)
-         */
-        webUrl?: string;
-        /**
-         * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
-         * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
-         */
-        subPageId?: string;
-        /**
-         * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
-         */
-        channelId?: string;
-        /**
-       * Optional ID of the chat or meeting where the app should be opened
-    
-       */
-        chatId?: string;
-    }
-    /**
-     * Type-safer version of parameters for the {@link pages.navigateToApp} function
-     */
-    interface AppNavigationParameters {
-        /**
-         * ID of the app to navigate to
-         */
-        appId: AppId;
-        /**
-         * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
-         */
-        pageId: string;
-        /**
-         * Fallback URL to open if the navigation cannot be completed within the host (e.g., if the target app is not installed)
-         */
-        webUrl?: URL;
-        /**
-         * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
-         * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
-         */
-        subPageId?: string;
-        /**
-         * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
-         * This property has no effect in hosts where apps cannot be opened in channels
-         */
-        channelId?: string;
-        /**
-         * Optional ID of the chat or meeting where the app should be opened
-         * This property has no effect in hosts where apps cannot be opened in chats or meetings
-         */
-        chatId?: string;
-    }
-    /**
-     * Provides APIs for querying and navigating between contextual tabs of an application. Unlike personal tabs,
-     * contextual tabs are pages associated with a specific context, such as channel or chat.
-     */
-    namespace tabs {
-        /**
-         * Navigates the hosted application to the specified tab instance.
-         * @param tabInstance - The destination tab instance.
-         * @returns Promise that resolves when the navigation has completed.
-         */
-        function navigateToTab(tabInstance: TabInstance): Promise<void>;
-        /**
-         * Retrieves application tabs for the current user.
-         * If no TabInstanceParameters are passed, the application defaults to favorite teams and favorite channels.
-         * @param tabInstanceParameters - An optional set of flags that specify whether to scope call to favorite teams or channels.
-         * @returns Promise that resolves with the {@link TabInformation}. Contains information for the user's tabs that are owned by this application {@link TabInstance}.
-         */
-        function getTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
-        /**
-         * Retrieves the most recently used application tabs for the current user.
-         * @param tabInstanceParameters - An optional set of flags. Note this is currently ignored and kept for future use.
-         * @returns Promise that resolves with the {@link TabInformation}. Contains information for the users' most recently used tabs {@link TabInstance}.
-         */
-        function getMruTabInstances(tabInstanceParameters?: TabInstanceParameters): Promise<TabInformation>;
-        /**
-         * Checks if the pages.tab capability is supported by the host
-         * @returns boolean to represent whether the pages.tab capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-    /**
-     * Provides APIs to interact with the configuration-specific part of the SDK.
-     * This object is usable only on the configuration frame.
-     */
-    namespace config {
-        /**
-         * @hidden
-         * Hide from docs because this function is only used during initialization
-         *
-         * Adds register handlers for settings.save and settings.remove upon initialization. Function is called in {@link app.initializeHelper}
-         * @internal
-         * Limited to Microsoft-internal use
-         */
-        function initialize(): void;
-        /**
-         * Sets the validity state for the configuration.
-         * The initial value is false, so the user cannot save the configuration until this is called with true.
-         * @param validityState - Indicates whether the save or remove button is enabled for the user.
-         */
-        function setValidityState(validityState: boolean): void;
-        /**
-         * Sets the configuration for the current instance.
-         * This is an asynchronous operation; calls to getConfig are not guaranteed to reflect the changed state.
-         * @param instanceConfig - The desired configuration for this instance.
-         * @returns Promise that resolves when the operation has completed.
-         */
-        function setConfig(instanceConfig: InstanceConfig): Promise<void>;
-        /**
-         * Registers a handler for when the user attempts to save the configuration. This handler should be used
-         * to create or update the underlying resource powering the content.
-         * The object passed to the handler must be used to notify whether to proceed with the save.
-         * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-         * @param handler - The handler to invoke when the user selects the Save button.
-         */
-        function registerOnSaveHandler(handler: saveEventType): void;
-        /**
-         * @hidden
-         * Undocumented helper function with shared code between deprecated version and current version of the registerOnSaveHandler API.
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         *
-         * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
-         * @param handler - The handler to invoke when the user selects the Save button.
-         * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
-         */
-        function registerOnSaveHandlerHelper(apiVersionTag: string, handler: (evt: SaveEvent) => void, versionSpecificHelper?: () => void): void;
-        /**
-         * Registers a handler for user attempts to remove content. This handler should be used
-         * to remove the underlying resource powering the content.
-         * The object passed to the handler must be used to indicate whether to proceed with the removal.
-         * Only one handler may be registered at a time. Subsequent registrations will override the first.
-         * @param handler - The handler to invoke when the user selects the Remove button.
-         */
-        function registerOnRemoveHandler(handler: removeEventType): void;
-        /**
-         * @hidden
-         * Undocumented helper function with shared code between deprecated version and current version of the registerOnRemoveHandler API.
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         *
-         * @param apiVersionTag - The API version tag, which is used for telemetry, composed by API version number and source API name.
-         * @param handler - The handler to invoke when the user selects the Remove button.
-         * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
-         */
-        function registerOnRemoveHandlerHelper(apiVersionTag: string, handler: (evt: RemoveEvent) => void, versionSpecificHelper?: () => void): void;
-        /**
-         * Registers a handler for when the tab configuration is changed by the user
-         * @param handler - The handler to invoke when the user clicks on Settings.
-         */
-        function registerChangeConfigHandler(handler: handlerFunctionType): void;
-        /**
-         * Describes the results of the settings.save event. Includes result, notifySuccess, and notifyFailure
-         * to indicate the return object (result) and the status of whether the settings.save call succeeded or not and why.
-         */
-        interface SaveEvent {
-            /**
-             * Object containing properties passed as arguments to the settings.save event.
-             */
-            result: SaveParameters;
-            /**
-             * Indicates that the underlying resource has been created and the config can be saved.
-             */
-            notifySuccess(): void;
-            /**
-             * Indicates that creation of the underlying resource failed and that the config cannot be saved.
-             * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
-             */
-            notifyFailure(reason?: string): void;
-        }
-        /**
-         * Describes the results of the settings.remove event. Includes notifySuccess, and notifyFailure
-         * to indicate the status of whether the settings.save call succeeded or not and why.
-         */
-        interface RemoveEvent {
-            /**
-             * Indicates that the underlying resource has been removed and the content can be removed.
-             */
-            notifySuccess(): void;
-            /**
-             * Indicates that removal of the underlying resource failed and that the content cannot be removed.
-             * @param reason - Specifies a reason for the failure. If provided, this string is displayed to the user; otherwise a generic error is displayed.
-             */
-            notifyFailure(reason?: string): void;
-        }
-        /**
-         * Parameters used in the settings.save event
-         */
-        interface SaveParameters {
-            /**
-             * Connector's webhook Url returned as arguments to settings.save event as part of user clicking on Save
-             */
-            webhookUrl?: string;
-        }
-        /**
-         * Checks if the pages.config capability is supported by the host
-         * @returns boolean to represent whether the pages.config capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-    /**
-     * Provides APIs for handling the user's navigational history.
-     */
-    namespace backStack {
-        /**
-         * @hidden
-         * Register backButtonPress handler.
-         *
-         * @internal
-         * Limited to Microsoft-internal use.
-         */
-        function _initialize(): void;
-        /**
-         * Navigates back in the hosted application. See {@link pages.backStack.registerBackButtonHandler} for notes on usage.
-         * @returns Promise that resolves when the navigation has completed.
-         */
-        function navigateBack(): Promise<void>;
-        /**
-         * Registers a handler for user presses of the host client's back button. Experiences that maintain an internal
-         * navigation stack should use this handler to navigate the user back within their frame. If an application finds
-         * that after running its back button handler it cannot handle the event it should call the navigateBack
-         * method to ask the host client to handle it instead.
-         * @param handler - The handler to invoke when the user presses the host client's back button.
-         */
-        function registerBackButtonHandler(handler: backButtonHandlerFunctionType): void;
-        /**
-         * @hidden
-         * Undocumented helper function with shared code between deprecated version and current version of the registerBackButtonHandler API.
-         *
-         * @internal
-         * Limited to Microsoft-internal use
-         * @param apiVersionTag - The tag indicating API version number with name
-         * @param handler - The handler to invoke when the user presses the host client's back button.
-         * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
-         */
-        function registerBackButtonHandlerHelper(apiVersionTag: string, handler: () => boolean, versionSpecificHelper?: () => void): void;
-        /**
-         * Checks if the pages.backStack capability is supported by the host
-         * @returns boolean to represent whether the pages.backStack capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-    /**
-     * @hidden
-     * Hide from docs
-     * ------
-     * Provides APIs to interact with the full-trust part of the SDK. Limited to 1P applications
-     * @internal
-     * Limited to Microsoft-internal use
-     */
-    namespace fullTrust {
-        /**
-         * @hidden
-         * Hide from docs
-         * ------
-         * Place the tab into full-screen mode.
-         *
-         */
-        function enterFullscreen(): void;
-        /**
-         * @hidden
-         * Hide from docs
-         * ------
-         * Reverts the tab into normal-screen mode.
-         */
-        function exitFullscreen(): void;
-        /**
-         * @hidden
-         *
-         * Checks if the pages.fullTrust capability is supported by the host
-         * @returns boolean to represent whether the pages.fullTrust capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-    /**
-     * Provides APIs to interact with the app button part of the SDK.
-     */
-    namespace appButton {
-        /**
-         * Registers a handler for clicking the app button.
-         * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-         * @param handler - The handler to invoke when the personal app button is clicked in the app bar.
-         */
-        function onClick(handler: handlerFunctionType): void;
-        /**
-         * Registers a handler for entering hover of the app button.
-         * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-         * @param handler - The handler to invoke when entering hover of the personal app button in the app bar.
-         */
-        function onHoverEnter(handler: handlerFunctionType): void;
-        /**
-         * Registers a handler for exiting hover of the app button.
-         * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
-         * @param handler - The handler to invoke when exiting hover of the personal app button in the app bar.
-         */
-        function onHoverLeave(handler: handlerFunctionType): void;
-        /**
-         * Checks if pages.appButton capability is supported by the host
-         * @returns boolean to represent whether the pages.appButton capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-    /**
-     * Provides functions for navigating within your own app
-     *
-     * @remarks
-     * If you are looking to navigate to a different app, use {@link pages.navigateToApp}.
-     */
-    namespace currentApp {
-        /**
-         * Parameters provided to the {@link pages.currentApp.navigateTo} function
-         */
-        interface NavigateWithinAppParams {
-            /**
-             * The developer-defined unique ID for the page defined in the manifest or when first configuring
-             * the page. (Known as {@linkcode Context.entityId} prior to TeamsJS v2.0.0)
-             */
-            pageId: string;
-            /**
-             * Optional developer-defined unique ID describing the content to navigate to within the page. This
-             * can be retrieved from the Context object {@link app.PageInfo.subPageId | app.Context.page.subPageId}
-             */
-            subPageId?: string;
-        }
-        /**
-         * Navigate within the currently running app
-         *
-         * @remarks
-         * If you are looking to navigate to a different app, use {@link pages.navigateToApp}.
-         *
-         * @param params Parameters for the navigation
-         * @returns `Promise` that will resolve if the navigation was successful and reject if not
-         */
-        function navigateTo(params: NavigateWithinAppParams): Promise<void>;
-        /**
-         * Navigate to the currently running app's first static page defined in the application
-         * manifest.
-         *
-         * @returns `Promise` that will resolve if the navigation was successful and reject if not
-         */
-        function navigateToDefaultPage(): Promise<void>;
-        /**
-         * Checks if pages.currentApp capability is supported by the host
-         * @returns boolean to represent whether the pages.currentApp capability is supported
-         *
-         * @throws Error if {@linkcode app.initialize} has not successfully completed
-         */
-        function isSupported(): boolean;
-    }
-}
-export declare function isAppNavigationParametersObject(obj: pages.AppNavigationParameters | pages.NavigateToAppParams): obj is pages.AppNavigationParameters;
-export declare function convertNavigateToAppParamsToAppNavigationParameters(params: pages.NavigateToAppParams): pages.AppNavigationParameters;
-export declare function convertAppNavigationParametersToNavigateToAppParams(params: pages.AppNavigationParameters): pages.NavigateToAppParams;