@microsoft/sp-adaptive-card-extension-base 1.13.1 → 1.14.0

package/dist/index-internal-beta.d.ts

@@ -27,8 +27,10 @@ import { IPropertyPaneConfiguration } from '@microsoft/sp-property-pane';
 import { IPropertyPaneGroup } from '@microsoft/sp-property-pane';
 import { ISDKs } from '@microsoft/sp-webpart-base';
 import { ISerializedServerProcessedData } from '@microsoft/sp-component-base';
+import { IShowCardAction } from 'adaptivecards/lib/schema';
 import { ISubmitAction } from 'adaptivecards/lib/schema';
 import { ITextBlock } from 'adaptivecards/lib/schema';
+import { ServiceKey } from '@microsoft/sp-core-library';
 import { ServiceScope } from '@microsoft/sp-core-library';
 import { Version } from '@microsoft/sp-core-library';
 
@@ -44,6 +46,7 @@ export declare class AdaptiveCardExtensionContext extends BaseComponentContext {
     readonly manifest: IAdaptiveCardExtensionManifest<unknown>;
     private _aceHost;
     private _deviceContext;
+    private _location;
     /* Excluded from this release type: __constructor */
     /* Excluded from this release type: _host */
     /**
@@ -51,6 +54,7 @@ export declare class AdaptiveCardExtensionContext extends BaseComponentContext {
      */
     get propertyPane(): IPropertyPaneAccessor | undefined;
     get deviceContext(): DeviceContext;
+    /* Excluded from this release type: location */
 }
 
 /* Excluded from this release type: _AdaptiveCardExtensionHost */
@@ -215,9 +219,25 @@ export declare class BaseAdaptiveCardExtension<TProperties = {}, TState = Readon
      * @virtual
      */
     protected loadPropertyPaneResources(): Promise<void>;
-    /* Excluded from this release type: getCacheSettings */
-    /* Excluded from this release type: getCachedState */
+    /**
+     * Override the default cache settings.
+     *
+     * @beta
+     * @virtual
+     */
+    protected getCacheSettings(): Partial<ICacheSettings>;
+    /**
+     * This virtual method returns a subset of the state object that will be cached by the client.
+     *
+     * @remarks If not overriden, this will return an empty object.
+     * @param state - A shallow clone of the AdaptiveCardExtension state object.
+     *
+     * @beta
+     * @virtual
+     */
+    protected getCachedState(state: TState): Partial<TState>;
     /* Excluded from this release type: _internalOnAction */
+    /* Excluded from this release type: _internalOnActionError */
     /**
      * Lifecycle method called before serialization.
      *
@@ -284,7 +304,19 @@ export declare class BaseAdaptiveCardExtension<TProperties = {}, TState = Readon
      * @virtual
      */
     onInit(): Promise<void>;
-    /* Excluded from this release type: onInit */
+    /**
+     * Lifecycle method called during initialization.
+     *
+     * @remarks Asynchronous data fetches should be started during this lifecycle. Rendering can either be dependent on the result
+     * or, if resolved immediately, a fetching data state can be rendered.
+     *
+     * @param cachedLoadParameters - Parameters containing the cached state object (see {@link BaseAdaptiveCardExtension.getCachedState}), which can be used to rehydrate the AdaptiveCardExtension.
+     * If undefined, the AdaptiveCardExtension was not cached or the cache expired.
+     *
+     * @beta
+     * @virtual
+     */
+    onInit(cachedLoadParameters?: ICachedLoadParameters): Promise<void>;
     /**
      * Lifecycle method called when a Property Pane field is changed.
      *
@@ -320,6 +352,7 @@ export declare class BaseAdaptiveCardExtension<TProperties = {}, TState = Readon
      */
     protected renderCard(): string | undefined;
     /* Excluded from this release type: _getPreFrameworkPropertyPaneConfiguration */
+    /* Excluded from this release type: _isFrameworkPropertyPaneEnabled */
     /**
      * Sets the visibility of the Adaptive Card Extension and re-render
      *
@@ -344,6 +377,16 @@ export declare class BaseAdaptiveCardExtension<TProperties = {}, TState = Readon
     /* Excluded from this release type: _getRenderArguments */
     /* Excluded from this release type: _propertiesMetadata */
     /* Excluded from this release type: _getPropertyPaneConfiguration */
+    /**
+     * The current {@link ViewNavigator}.
+     *
+     * @remarks If the current {@link BaseAdaptiveCardExtension.renderType} is `Card`
+     * then returns {@link BaseAdaptiveCardExtension.cardNavigator}.
+     *
+     * @remarks If the current {@link BaseAdaptiveCardExtension.renderType} is `QuickView`
+     * then returns {@link BaseAdaptiveCardExtension.quickViewNavigator}.
+     */
+    get navigator(): ViewNavigator<BaseView<TProperties, TState>>;
     /* Excluded from this release type: _internalDeserialize */
     /* Excluded from this release type: _internalInitialize */
     /* Excluded from this release type: _internalSetDisplayMode */
@@ -585,6 +628,14 @@ export declare abstract class BaseView<TProperties = {}, TState = {}, TData = {}
      * @param action - The {@link IActionArguments} for the current event.
      */
     onAction(action: IActionArguments): void;
+    /**
+     * @beta
+     *
+     * Error handler for Adaptive Card Actions.
+     *
+     * @param error - The {@link IActionErrorArguments} for the current event.
+     */
+    onActionError(error: IActionErrorArguments): void;
     /**
      * See {@link BaseAdaptiveCardExtension.setState}.
      */
@@ -609,16 +660,32 @@ export declare type CardSize = 'Medium' | 'Large';
  *
  * @public
  */
-export declare type DeviceContext = 'WebView' | 'Mobile';
+export declare type DeviceContext = 'WebView' | 'Mobile' | 'TeamsDesktop';
 
 /**
  * The object passed to {@link BaseView.onAction} when an Adaptive Card Action is executed.
  *
- * @remarks Only `Submit`, `ShowCard` and 'SelectMedia' actions are routed to the {@link BaseView.onAction} handler.
+ * @remarks Only `Submit`, `ShowCard`, 'Viva.SelectMedia', 'Viva.GetLocation' and 'Viva.ShowLocation; actions are routed to the {@link BaseView.onAction} handler.
  *
  * @public
  */
-export declare type IActionArguments = ISubmitActionArguments | IShowCardActionArguments;
+export declare type IActionArguments = ISubmitActionArguments | IShowCardActionArguments | ISelectMediaActionArguments | IGetLocationActionArguments;
+
+/**
+ * @beta
+ */
+export declare type IActionError = {
+    code: string;
+};
+
+/**
+ * The object passed to {@link BaseView.onActionError} when an Adaptive Card Action is executed.
+ *
+ * @remarks Only `Submit`, `ShowCard`, 'Viva.SelectMedia', 'Viva.GetLocation' and 'Viva.ShowLocation; actions are routed to the {@link BaseView.onActionError} handler.
+ *
+ * @public
+ */
+export declare type IActionErrorArguments = IBaseActionErrorArguments | ISelectMediaActionErrorArguments | ILocationErrorArguments;
 
 /* Excluded from this release type: _IAdaptiveCardExtension */
 
@@ -653,6 +720,19 @@ export declare interface IAdaptiveCardExtensionPropertyMetadata extends ICompone
 
 /* Excluded from this release type: _IAdaptiveCardRenderParameters */
 
+/**
+ * This object represents error associated with a single attachment
+ * @remarks API under active development and not ready for use.
+ * @public
+ */
+export declare interface IAttachmentError {
+    /**
+     * Error code associated with a particular attachment
+     * @beta
+     */
+    errorCode: 'FileTooLarge' | 'IncorrectFileFormat';
+}
+
 /**
  * Base object passed to {@link BaseView.onAction} when an Adaptive Card Action is executed.
  *
@@ -671,6 +751,29 @@ export declare interface IBaseActionArguments {
     id?: string;
 }
 
+/**
+ * Base object passed to {@link BaseView.onActionError} when an Adaptive Card OnActionError is executed.
+ *
+ *  @public
+ */
+export declare interface IBaseActionErrorArguments {
+    /**
+     * The type of Adaptive Card Action thsat caused the error.
+     * @beta
+     */
+    type: 'Submit' | 'ShowCard' | 'VivaAction.SelectMedia' | 'VivaAction.GetLocation' | 'VivaAction.ShowLocation';
+    /**
+     * The id specified in the Adaptive Card template
+     * @beta
+     */
+    id?: string;
+    /**
+     * The error thrown by the action
+     * @beta
+     */
+    error: IActionError;
+}
+
 /**
  * The primitive data parameters for every Card view.
  *
@@ -696,6 +799,14 @@ export declare interface IBaseCardParameters {
     title?: string;
 }
 
+/* Excluded from this release type: IBaseIsolatedApplicationMessage */
+
+/* Excluded from this release type: _IBaseIsolatedMessage */
+
+/* Excluded from this release type: IBaseIsolatedServiceCallbackParameters */
+
+/* Excluded from this release type: _IBaseIsolatedServiceMessage */
+
 /**
  * The data parameters for {@link BaseBasicCardView}.
  *
@@ -708,9 +819,35 @@ export declare interface IBasicCardParameters extends IBaseCardParameters {
     primaryText: string;
 }
 
-/* Excluded from this release type: ICachedLoadParameters */
+/**
+ * Parameters used to rehydrate the AdaptiveCardExtension during a cached load
+ *
+ * @beta
+ * @remarks API under active development and not ready for use.
+ */
+export declare interface ICachedLoadParameters {
+    state: any;
+    cardNavigatorState: string[];
+}
 
-/* Excluded from this release type: ICacheSettings */
+/**
+ * @beta
+ */
+export declare interface ICacheSettings {
+    /**
+     * Whether cache is enabled. Default: true
+     */
+    isEnabled: boolean;
+    /**
+     * Expiry time in seconds. Default: 86400 seconds (24 hours)
+     */
+    expiryTimeInSeconds: number;
+    /**
+     * Returns the Card View used to generate the cached card.
+     * By default, the currently rendered Card View will be used to cache the card.
+     */
+    cachedCardView?: () => BaseCardView;
+}
 
 /**
  * Type of handler for when a button is pressed.
@@ -797,15 +934,17 @@ export declare interface IExternalLinkParameters {
 /**
  * Interface for Viva Get Location action
  * @remarks API under active development and not ready for use.
- * @beta
+ * @public
  */
 export declare interface IGetLocationAction extends IAction {
     /**
      * Indicates this is a Viva Select Location button.
+     * @beta
      */
     type: 'VivaAction.GetLocation';
     /**
      * Parameters that can be supplied with the Viva Get Location Action.
+     * @beta
      */
     parameters?: IGetLocationActionParameters;
 }
@@ -813,16 +952,18 @@ export declare interface IGetLocationAction extends IAction {
 /**
  * The object passed to {@link BaseView.onAction} when a Get location Action is executed.
  * @remarks API under active development and not ready for use.
- * @beta
+ * @public
  */
 export declare interface IGetLocationActionArguments extends Omit<IBaseActionArguments, 'type'> {
     /**
      * The type of Adaptive Card Action.
+     * @beta
      */
     type: 'VivaAction.GetLocation';
     /**
      * Coordinates of the location.
      * In case of erroneous situation, location object will be undefined.
+     * @beta
      */
     location?: ILocation;
 }
@@ -873,9 +1014,31 @@ export declare interface IImageCardParameters extends IBaseCardParameters {
     primaryText: string;
 }
 
+/* Excluded from this release type: _IIsolatedAction */
+
+/* Excluded from this release type: _IIsolatedActionServiceMessage */
+
+/* Excluded from this release type: _IIsolatedErrorCallbackParameters */
+
+/* Excluded from this release type: _IIsolatedErrorMessage */
+
+/* Excluded from this release type: _IIsolatedInitializeServiceMessage */
+
+/* Excluded from this release type: _IIsolatedReadyMessage */
+
+/* Excluded from this release type: _IIsolatedRenderCallbackParameters */
+
+/* Excluded from this release type: _IIsolatedRenderMessage */
+
+/* Excluded from this release type: _IIsolatedTokenRequestMessage */
+
+/* Excluded from this release type: IIsolatedVisibilityChangeCallbackParameters */
+
+/* Excluded from this release type: _ILoadIsolatedAdaptiveCardExtensionParameters */
+
 /**
  * Interface for location coordinates
- * @remarks API under active development and not ready for use.
+ * @remarks API under active development and is not ready for use.
  * @beta
  */
 export declare interface ILocation {
@@ -897,8 +1060,30 @@ export declare interface ILocation {
     accuracy?: number;
 }
 
+/**
+ * This object represents the error data that the Location action can throw.
+ * @remarks API under active development and not ready for use.
+ * @public
+ */
+export declare interface ILocationErrorArguments extends Omit<IBaseActionErrorArguments, 'type'> {
+    /**
+     * Indicates this is a Viva Select Location button.
+     * @beta
+     */
+    type: 'VivaAction.GetLocation';
+    /**
+     * Error codes specific to the Get Location Error
+     * @beta
+     */
+    error: {
+        code: 'InternalError' | 'PermissionDenied';
+    };
+}
+
 /* Excluded from this release type: _INavigationBarProperties */
 
+/* Excluded from this release type: _IOpenUrlActionArgument */
+
 /**
  * The data parameters for {@link BasePrimaryTextCardView}.
  *
@@ -915,6 +1100,8 @@ export declare interface IPrimaryTextCardParameters extends IBaseCardParameters
     primaryText: string;
 }
 
+/* Excluded from this release type: _IQuickViewActionArgument */
+
 /**
  * Open the quick view.
  *
@@ -947,6 +1134,10 @@ export declare interface IQuickViewParameters {
 
 /* Excluded from this release type: _IQuickViewSubmitData */
 
+/* Excluded from this release type: _IRenderIsolatedQuickViewParameters */
+
+/* Excluded from this release type: _isAdaptiveCardExtensionLKGCachingEnabled */
+
 /* Excluded from this release type: _ISelectActionTemplateAdaptiveCard */
 
 /* Excluded from this release type: _ISelectActionTemplateContainer */
@@ -954,27 +1145,67 @@ export declare interface IQuickViewParameters {
 /**
  * Interface for new Viva Select Media action
  * @remarks API under active development and not ready for use.
- * @beta
+ * @public
  */
 export declare interface ISelectMediaAction extends IAction {
+    /**
+     * Indicates this is a Viva Select Location button.
+     * @beta
+     */
     type: 'VivaAction.SelectMedia';
+    /**
+     * Parameters that can be provided to the ISelectMedia Action
+     * @beta
+     */
     parameters: ISelectMediaActionParameters;
 }
 
 /**
  * The object passed to {@link BaseView.onAction} when a `SelectMedia` Action is executed.
  * @remarks API under active development and not ready for use.
- * @beta
+ * @public
  */
 export declare interface ISelectMediaActionArguments extends Omit<IBaseActionArguments, 'type'> {
     /**
      * The type of Adaptive Card Action.
+     * @beta
      */
     type: 'VivaAction.SelectMedia';
     /**
      * media object returned media picker API
+     * @beta
      */
     media: ISelectMediaAttachment[];
+    /**
+     * Submit Action data that is passed to internal action handler to ensure forms do not clear.
+     * @beta
+     */
+    data: any;
+}
+
+/**
+ * This object represents the data returned by the native media picker API.
+ * @remarks API under active development and not ready for use.
+ * @public
+ */
+export declare interface ISelectMediaActionErrorArguments extends Omit<IBaseActionErrorArguments, 'type'> {
+    /**
+     * The type of Adaptive Card Action.
+     * @beta
+     */
+    type: 'VivaAction.SelectMedia';
+    /**
+     * media object returned media picker API
+     * @beta
+     */
+    media: ISelectMediaAttachment[] | undefined;
+    /**
+     * Error codes specific to the Select Media Action.
+     * @beta
+     */
+    error: {
+        code: 'FileSelectionFailed' | 'FilesSelectedAreIncompatible';
+    };
 }
 
 /**
@@ -1015,6 +1246,10 @@ export declare interface ISelectMediaAttachment {
      * Content of the file represented as base64Strings
      */
     content: string;
+    /**
+     * Error associated with attachment
+     */
+    error?: IAttachmentError;
 }
 
 /**
@@ -1028,7 +1263,7 @@ export declare interface ISelectMediaCardAction {
      */
     type: 'VivaAction.SelectMedia';
     /**
-     * Parameters for the external link.
+     * Parameters for the Select Media Action
      */
     parameters: ISelectMediaActionParameters;
 }
@@ -1048,15 +1283,17 @@ export declare interface IShowCardActionArguments extends IBaseActionArguments {
 /**
  * Interface for Viva Show Location action
  * @remarks API under active development and not ready for use.
- * @beta
+ * @public
  */
 export declare interface IShowLocationAction extends IAction {
     /**
      * Indicates this is a Viva show Location button.
+     * @beta
      */
     type: 'VivaAction.ShowLocation';
     /**
      * Parameters that can be supplied with the Viva Show Location Action.
+     * @beta
      */
     parameters?: IShowLocationActionParameters;
 }
@@ -1090,12 +1327,26 @@ export declare interface IShowLocationCardAction {
     parameters?: IShowLocationActionParameters;
 }
 
+/* Excluded from this release type: _IsolatedAdaptiveCardExtensionApplicationMessageEvent */
+
+/* Excluded from this release type: _IsolatedAdaptiveCardExtensionService */
+
+/* Excluded from this release type: _IsolatedAdaptiveCardExtensionServiceCallback */
+
+/* Excluded from this release type: _IsolatedServiceCallbackParameters */
+
+/* Excluded from this release type: _IsolatedServiceMessageEvent */
+
 /**
  * SPFx Adaptive Card Extension schema for Adaptive Cards.
  *
  * @public
  */
-export declare interface ISPFxAdaptiveCard extends IAdaptiveCard {
+export declare interface ISPFxAdaptiveCard extends Omit<IAdaptiveCard, 'actions'> {
+    /**
+     * Types of actions being exposed
+     */
+    actions?: (ISubmitAction | IOpenUrlAction | IShowCardAction | ISelectMediaAction | IGetLocationAction | IShowLocationAction)[];
 }
 
 /**