/** * (c) Copyright Ascensio System SIA 2026 * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * * @license */ /** * @packageDocumentation * * Here is a description of the module Utils. * * @categoryDescription Message * * Here is a description of the category Message. * * @categoryDescription PostMessage * * Here is a description of the category PostMessage. * * @categoryDescription PostMessageCallbackMessage * * Here is a description of the category PostMessageCallbackMessage. * * @module Utils */ import { Actions } from "../../enums"; import { IBox, IButton, ICheckbox, IComboBox, ICreateDialog, IFloatingOperationsButton, IFrame, IImage, IInput, ILabel, IModalDialog, ISkeleton, IText, ITextArea, IToast, IToggleButton, IMediaViewer } from "../components"; import { TSelector } from "../components/Selector/ISelector"; /** * Defines the info panel tab to open. * * @category InfoPanelTab */ export type TInfoPanelTab = "info_members" | "info_history" | "info_details" | "info_share" | string; /** * The properties that are used to send a message to a frame. * If the frame ID is not specified or the frame with such an ID does not exist, then nothing changes. * * @category PostMessage * * @example * * Document preview frame communication * * ```typescript * const previewMessage: IPostMessage = { * frameId: "document-preview-frame", * message: { * action: "zoom", * scale: 1.5, * position: { x: 100, y: 200 } * } * }; * ``` */ export interface IPostMessage { /** Defines the frame ID */ frameId: string; /** Defines a message that will be sent to a frame */ message: { [key: string]: any; }; } /** * A message which is returned when any item interacts with a user (onClick, onChange, onSelect, etc.). * * @category Message * * @example * * Form submission with validation and toast notification * * ```typescript * const formSubmissionMessage: IMessage = { * actions: [Actions.updateProps, Actions.showToast, Actions.updateContext], * newProps: { * type: "input", * id: "email-input", * value: "user@example.com", * isDisabled: true * }, * toastProps: [{ * type: "success", * title: "Form Submitted", * message: "Your data has been saved successfully" * }], * contextProps: [{ * name: "submit-button", * props: { * type: "button", * label: "Submitted", * isDisabled: true * } * }] * }; * ``` * * @example * * Dynamic form field updates with error handling * * ```typescript * const fieldUpdateMessage: IMessage = { * actions: [Actions.updateProps, Actions.showToast, Actions.updateContext], * newProps: { * type: "comboBox", * id: "country-select", * options: [ * { value: "us", label: "United States" }, * { value: "uk", label: "United Kingdom" } * ], * value: "us" * }, * toastProps: [{ * type: "error", * title: "Validation Error", * message: "Please complete all required fields" * }], * contextProps: [{ * name: "state-select", * props: { * type: "comboBox", * options: [ * { value: "ca", label: "California" }, * { value: "ny", label: "New York" } * ], * isDisabled: false * } * }] * }; * ``` */ export interface IMessage { /** * Defines a collection of events that will be processed on the portal side. * The specified actions will be performed depending on the set of values. */ actions?: Actions[]; /** * Defines the properties that update the state of the items which interact with the users. * This parameter is used only with Actions.updateProps. */ newProps?: IInput | ICheckbox | IToggleButton | IButton | ITextArea | IComboBox; /** * Defines the properties that display a toast notification after the user actions. * This parameter is used only with Actions.showToast. */ toastProps?: IToast[]; /** * Defines the properties that update the state of the parent or child item after the event was executed. * Contains an array of objects with: * - name: Defines the item name * - props: Defines the new properties for the parent or child item */ contextProps?: { name: string; props: IBox | IButton | ICheckbox | IComboBox | IFrame | IImage | IInput | ILabel | ISkeleton | IText | ITextArea | IToggleButton; }[]; /** * Defines the properties that display the default dialog box for creating a file/folder managed by the plugin. * This parameter is used only with Actions.showCreateDialogModal. */ createDialogProps?: ICreateDialog; /** * Defines the properties that display the modal window. * This parameter is used only with Actions.showModal. */ modalDialogProps?: IModalDialog; /** * Defines the properties that display the selector. * This parameter is used only with Actions.showSelector. */ selectorProps?: TSelector; /** * Defines the configuration for the floating operations button that displays progress of long-running operations. * Used with Actions.addFloatingOperationsButton to create a new button or Actions.updateFloatingOperationsButton to update existing one. * The button appears as a floating action button in the bottom-right corner. Multiple plugins can show operations simultaneously. */ floatingOperationsButtonProps?: IFloatingOperationsButton; /** * Unique identifier for the floating operations button to remove. * Used only with Actions.removeFloatingOperationsButton to close a specific operations panel. * The ID should match the `id` property of the IFloatingOperationsButton that was previously added. */ floatingOperationsButtonPropsId?: string; /** * Defines the properties that are used to send a message to a frame. * If the frame ID is not specified or the frame with such an ID does not exist, then nothing changes. * This parameter is used only with Actions.sendPostMessage. */ postMessage?: IPostMessage; /** * Defines a parameter that is used to save and transfer the administrator or owner plugin settings to all the portal users. * This parameter is used only with Actions.saveSettings. */ settings?: string; /** * Defines the path to navigate to. * All actions listed after navigate will be called after the navigation is complete. * This parameter is used only with Actions.navigate. */ navigatePath?: string; /** * Defines the info panel tab to open. * This parameter is used only with Actions.openInfoPanel. */ infoPanelTab?: TInfoPanelTab; /** * Defines the properties for the media viewer. * This parameter is used only with Actions.showMediaViewer and Actions.updateMediaViewer. */ mediaViewerProps?: IMediaViewer; } /** * A message which is returned from the postMessage callback. * It is similar to {@link IMessage} but with a reduced set of available actions. * * @category PostMessageCallbackMessage * * @example * * Handling a postMessage callback with a toast notification * * ```typescript * const postMessageResponse: IPostMessageCallbackMessage = { * actions: [Actions.showToast], * toastProps: [{ * type: "success", * title: "Message Received", * message: "Frame message processed successfully" * }] * }; * ``` */ export interface IPostMessageCallbackMessage { /** * Defines a collection of events that will be processed on the portal side. * Only the following actions are available: * updateContextMenuItems, updateInfoPanelItems, updateMainButtonItems, * updateProfileMenuItems, updateFileItems, updateEventListenerItems, * showToast, showCreateDialogModal, showModal, showSelector, addFloatingOperationsButton, * navigate, openInfoPanel. */ actions?: (Actions.updateContextMenuItems | Actions.updateInfoPanelItems | Actions.updateMainButtonItems | Actions.updateProfileMenuItems | Actions.updateFileItems | Actions.updateEventListenerItems | Actions.showToast | Actions.showCreateDialogModal | Actions.showModal | Actions.showSelector | Actions.showMediaViewer | Actions.addFloatingOperationsButton | Actions.navigate | Actions.openInfoPanel | Actions.closeModal | Actions.closeMediaViewer | Actions.removeFloatingOperationsButton)[]; /** * Defines the properties that display a toast notification after the user actions. * This parameter is used only with Actions.showToast. */ toastProps?: IToast[]; /** * Defines the properties that display the default dialog box for creating a file/folder managed by the plugin. * This parameter is used only with Actions.showCreateDialogModal. */ createDialogProps?: ICreateDialog; /** * Defines the properties that display the modal window. * This parameter is used only with Actions.showModal. */ modalDialogProps?: IModalDialog; /** * Defines the properties that display the selector. * This parameter is used only with Actions.showSelector. */ selectorProps?: TSelector; /** * Defines the configuration for the floating operations button that displays progress of long-running operations. * Used with Actions.addFloatingOperationsButton to create a new button. */ floatingOperationsButtonProps?: IFloatingOperationsButton; /** * Unique identifier for the floating operations button to remove. * Used with Actions.removeFloatingOperationsButton to close a specific operations panel. * The ID should match the `id` property of the IFloatingOperationsButton that was previously added. */ floatingOperationsButtonPropsId?: IFloatingOperationsButton["id"]; /** * Defines the path to navigate to. * All actions listed after navigate will be called after the navigation is complete. * This parameter is used only with Actions.navigate. */ navigatePath?: string; /** * Defines the info panel tab to open. * This parameter is used only with Actions.openInfoPanel. */ infoPanelTab?: TInfoPanelTab; } export type TReturnPostMessage = Promise | Promise | void | IPostMessageCallbackMessage; export type TReturnMessage = Promise | Promise | void | IMessage;