roosterjs 8.25.0 → 8.26.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.25.0)
+// Type definitions for roosterjs (Version 8.26.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -338,6 +338,7 @@ function applyTextStyle(container: Node, styler: (node: HTMLElement, isInnerNode
  * @param event The paste event
  * @param callback Callback function when data is ready
  * @param options Options to retrieve more items from the event, including HTML string and other customized items
+ * @param rangeBeforePaste Optional range to be removed when pasting in Android
  * @returns An object with the following properties:
  *  types: Available types from the clipboard event
  *  text: Plain text from the clipboard event
@@ -346,7 +347,7 @@ function applyTextStyle(container: Node, styler: (node: HTMLElement, isInnerNode
  *   When set to undefined, it means can't retrieve HTML string, there may be HTML string but direct retrieving is
  *   not supported by browser.
  */
-function extractClipboardEvent(event: ClipboardEvent, callback: (clipboardData: ClipboardData) => void, options?: ExtractClipboardEventOption): void;
+function extractClipboardEvent(event: ClipboardEvent, callback: (clipboardData: ClipboardData) => void, options?: ExtractClipboardEventOption, rangeBeforePaste?: Range): void;
 
     /**
  * Extract clipboard items to be a ClipboardData object for IE
@@ -2561,7 +2562,7 @@ function toggleListType(editor: IEditor, listType: ListType | CompatibleListType
     /**
  * Split selection into regions, and perform a block-wise formatting action for each region.
  */
-function blockFormat(editor: IEditor, callback: (region: Region, start: NodePosition, end: NodePosition, chains: VListChain[]) => void, beforeRunCallback?: () => boolean): void;
+function blockFormat(editor: IEditor, callback: (region: Region, start: NodePosition, end: NodePosition, chains: VListChain[]) => void, beforeRunCallback?: () => boolean, apiName?: string): void;
 
     /**
  * Commit changes of all list changes when experiment features are allowed
@@ -4208,7 +4209,13 @@ const enum DefinitionType {
     /**
  * Provides a chance for plugin to change the content before it is copied from editor.
  */
-interface BeforeCutCopyEvent extends BasePluginEvent<PluginEventType.BeforeCutCopy> {
+interface BeforeCutCopyEvent extends BeforeCutCopyEventData, BasePluginEvent<PluginEventType.BeforeCutCopy> {
+}
+
+    /**
+ * Data of BeforeCutCopyEvent
+ */
+interface BeforeCutCopyEventData {
     /**
      * Raw DOM event
      */
@@ -4227,6 +4234,12 @@ interface BeforeCutCopyEvent extends BasePluginEvent<PluginEventType.BeforeCutCo
     isCut: boolean;
 }
 
+    /**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+interface CompatibleBeforeCutCopyEvent extends BeforeCutCopyEventData, BasePluginEvent<CompatiblePluginEventType.BeforeCutCopy> {
+}
+
     /**
  * Editor plugin event interface
  */
@@ -4254,7 +4267,19 @@ interface BeforeDisposeEvent extends BasePluginEvent<PluginEventType.BeforeDispo
     /**
  * Provides a chance for plugin to change the content before it is pasted into editor.
  */
-interface BeforePasteEvent extends BasePluginEvent<PluginEventType.BeforePaste> {
+interface CompatibleBeforeDisposeEvent extends BasePluginEvent<CompatiblePluginEventType.BeforeDispose> {
+}
+
+    /**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+interface BeforePasteEvent extends BeforePasteEventData, BasePluginEvent<PluginEventType.BeforePaste> {
+}
+
+    /**
+ * Data of BeforePasteEvent
+ */
+interface BeforePasteEventData {
     /**
      * An object contains all related data for pasting
      */
@@ -4281,21 +4306,46 @@ interface BeforePasteEvent extends BasePluginEvent<PluginEventType.BeforePaste>
     htmlAttributes: Record<string, string>;
 }
 
+    /**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+interface CompatibleBeforePasteEvent extends BeforePasteEventData, BasePluginEvent<CompatiblePluginEventType.BeforePaste> {
+}
+
     /**
  * The event to be triggered before SetContent API is called.
  * Handle this event to cache anything you need from editor before it is gone.
  */
-interface BeforeSetContentEvent extends BasePluginEvent<PluginEventType.BeforeSetContent> {
+interface BeforeSetContentEvent extends BeforeSetContentEventData, BasePluginEvent<PluginEventType.BeforeSetContent> {
+}
+
+    /**
+ * Data of BeforeSetContentEvent
+ */
+interface BeforeSetContentEventData {
     /**
      * New content HTML that is about to set to editor
      */
     newContent: string;
 }
 
+    /**
+ * The event to be triggered before SetContent API is called.
+ * Handle this event to cache anything you need from editor before it is gone.
+ */
+interface CompatibleBeforeSetContentEvent extends BeforeSetContentEventData, BasePluginEvent<CompatiblePluginEventType.BeforeSetContent> {
+}
+
     /**
  * Represents a change to the editor made by another plugin
  */
-interface ContentChangedEvent extends BasePluginEvent<PluginEventType.ContentChanged> {
+interface ContentChangedEvent extends ContentChangedEventData, BasePluginEvent<PluginEventType.ContentChanged> {
+}
+
+    /**
+ * Data of ContentChangedEvent
+ */
+interface ContentChangedEventData {
     /**
      * Source of the change
      */
@@ -4304,13 +4354,26 @@ interface ContentChangedEvent extends BasePluginEvent<PluginEventType.ContentCha
      * Optional related data
      */
     data?: any;
+    additionalData?: ContentChangedData;
+}
+
+    /**
+ * Represents a change to the editor made by another plugin
+ */
+interface CompatibleContentChangedEvent extends ContentChangedEventData, BasePluginEvent<CompatiblePluginEventType.ContentChanged> {
 }
 
     /**
  * Represents an event that will be fired when an inline image is edited by user, and the src
  * attribute of the image is about to be changed
  */
-interface EditImageEvent extends BasePluginEvent<PluginEventType.EditImage> {
+interface EditImageEvent extends EditImageEventData, BasePluginEvent<PluginEventType.EditImage> {
+}
+
+    /**
+ * Data of EditImageEvent
+ */
+interface EditImageEventData {
     /**
      * The image element that is being changed
      */
@@ -4331,17 +4394,36 @@ interface EditImageEvent extends BasePluginEvent<PluginEventType.EditImage> {
     newSrc: string;
 }
 
+    /**
+ * Represents an event that will be fired when an inline image is edited by user, and the src
+ * attribute of the image is about to be changed
+ */
+interface CompatibleEditImageEvent extends EditImageEventData, BasePluginEvent<CompatiblePluginEventType.EditImage> {
+}
+
     /**
  * Provides a chance for plugin to change the content before it is pasted into editor.
  */
 interface EditorReadyEvent extends BasePluginEvent<PluginEventType.EditorReady> {
+}
+
+    /**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+interface CompatibleEditorReadyEvent extends BasePluginEvent<CompatiblePluginEventType.EditorReady> {
 }
 
     /**
  * Provide a chance for plugins to handle entity related events.
  * See enum EntityOperation for more details about each operation
  */
-interface EntityOperationEvent extends BasePluginEvent<PluginEventType.EntityOperation> {
+interface EntityOperationEvent extends EntityOperationEventData, BasePluginEvent<PluginEventType.EntityOperation> {
+}
+
+    /**
+ * Data of EntityOperationEvent
+ */
+interface EntityOperationEventData {
     /**
      * Operation to this entity
      */
@@ -4368,13 +4450,26 @@ interface EntityOperationEvent extends BasePluginEvent<PluginEventType.EntityOpe
     contentForShadowEntity?: DocumentFragment;
 }
 
+    /**
+ * Provide a chance for plugins to handle entity related events.
+ * See enum EntityOperation for more details about each operation
+ */
+interface CompatibleEntityOperationEvent extends EntityOperationEventData, BasePluginEvent<CompatiblePluginEventType.EntityOperation> {
+}
+
     /**
  * Extract Content with a DOM tree event
  * This event is triggered when getContent() is called with triggerExtractContentEvent = true
  * Plugin can handle this event to remove the UI only markups to return clean HTML
  * by operating on a cloned DOM tree
  */
-interface ExtractContentWithDomEvent extends BasePluginEvent<PluginEventType.ExtractContentWithDom> {
+interface ExtractContentWithDomEvent extends ExtractContentWithDomEventData, BasePluginEvent<PluginEventType.ExtractContentWithDom> {
+}
+
+    /**
+ * Data of ExtractContentWithDomEvent
+ */
+interface ExtractContentWithDomEventData {
     /**
      * Cloned root element of editor
      * Plugin can change this DOM tree to clean up the markups it added before
@@ -4382,6 +4477,15 @@ interface ExtractContentWithDomEvent extends BasePluginEvent<PluginEventType.Ext
     clonedRoot: HTMLElement;
 }
 
+    /**
+ * Extract Content with a DOM tree event
+ * This event is triggered when getContent() is called with triggerExtractContentEvent = true
+ * Plugin can handle this event to remove the UI only markups to return clean HTML
+ * by operating on a cloned DOM tree
+ */
+interface CompatibleExtractContentWithDomEvent extends ExtractContentWithDomEventData, BasePluginEvent<CompatiblePluginEventType.ExtractContentWithDom> {
+}
+
     /**
  * An event fired when pending format state (bold, italic, underline, ... with collapsed selection) is changed
  */
@@ -4389,6 +4493,13 @@ interface PendingFormatStateChangedEvent extends BasePluginEvent<PluginEventType
     formatState: PendableFormatState;
 }
 
+    /**
+ * An event fired when pending format state (bold, italic, underline, ... with collapsed selection) is changed
+ */
+interface CompatiblePendingFormatStateChangedEvent extends BasePluginEvent<CompatiblePluginEventType.PendingFormatStateChanged> {
+    formatState: PendableFormatState;
+}
+
     /**
  * This represents a PluginEvent wrapping native browser event
  */
@@ -4410,13 +4521,7 @@ interface PluginCompositionEvent extends PluginDomEventBase<PluginEventType.Comp
     /**
  * This interface represents a PluginEvent wrapping native ContextMenu event
  */
-interface PluginContextMenuEvent extends PluginDomEventBase<PluginEventType.ContextMenu, MouseEvent> {
-    /**
-     * A callback array to let editor retrieve context menu item related to this event.
-     * Plugins can add their own getter callback to this array,
-     * items from each getter will be separated by a splitter item represented by null
-     */
-    items: any[];
+interface PluginContextMenuEvent extends PluginContextMenuEventData, PluginDomEventBase<PluginEventType.ContextMenu, MouseEvent> {
 }
 
     /**
@@ -4456,11 +4561,7 @@ interface PluginMouseDownEvent extends PluginDomEventBase<PluginEventType.MouseD
     /**
  * This interface represents a PluginEvent wrapping native MouseUp event
  */
-interface PluginMouseUpEvent extends PluginDomEventBase<PluginEventType.MouseUp, MouseEvent> {
-    /**
-     * Whether this is a mouse click event (mouse up and down on the same position)
-     */
-    isClicking?: boolean;
+interface PluginMouseUpEvent extends PluginMouseUpEventData, PluginDomEventBase<PluginEventType.MouseUp, MouseEvent> {
 }
 
     /**
@@ -4472,14 +4573,114 @@ interface PluginInputEvent extends PluginDomEventBase<PluginEventType.Input, Inp
     /**
  * This interface represents a PluginEvent wrapping native scroll event
  */
-interface PluginScrollEvent extends PluginDomEventBase<PluginEventType.Scroll, UIEvent> {
+interface PluginScrollEvent extends PluginScrollEventData, PluginDomEventBase<PluginEventType.Scroll, UIEvent> {
+}
+
+    /**
+ * This represents a PluginEvent wrapping native browser event
+ */
+type CompatiblePluginDomEvent = CompatiblePluginCompositionEvent | CompatiblePluginMouseEvent | CompatiblePluginKeyboardEvent | CompatiblePluginInputEvent | CompatiblePluginScrollEvent;
+
+    /**
+ * This interface represents a PluginEvent wrapping native CompositionEnd event
+ */
+interface CompatiblePluginCompositionEvent extends PluginDomEventBase<CompatiblePluginEventType.CompositionEnd, CompositionEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native ContextMenu event
+ */
+interface CompatiblePluginContextMenuEvent extends PluginContextMenuEventData, PluginDomEventBase<CompatiblePluginEventType.ContextMenu, MouseEvent> {
+}
+
+    /**
+ * The interface represents a PluginEvent wrapping native Keyboard event
+ */
+type CompatiblePluginKeyboardEvent = CompatiblePluginKeyDownEvent | CompatiblePluginKeyPressEvent | CompatiblePluginKeyUpEvent;
+
+    /**
+ * This interface represents a PluginEvent wrapping native KeyDown event
+ */
+interface CompatiblePluginKeyDownEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyDown, KeyboardEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native KeyPress event
+ */
+interface CompatiblePluginKeyPressEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyPress, KeyboardEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native KeyUp event
+ */
+interface CompatiblePluginKeyUpEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyUp, KeyboardEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native Mouse event
+ */
+type CompatiblePluginMouseEvent = CompatiblePluginMouseDownEvent | CompatiblePluginMouseUpEvent | CompatiblePluginContextMenuEvent;
+
+    /**
+ * This interface represents a PluginEvent wrapping native MouseDown event
+ */
+interface CompatiblePluginMouseDownEvent extends PluginDomEventBase<CompatiblePluginEventType.MouseDown, MouseEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native MouseUp event
+ */
+interface CompatiblePluginMouseUpEvent extends PluginMouseUpEventData, PluginDomEventBase<CompatiblePluginEventType.MouseUp, MouseEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native input / textinput event
+ */
+interface CompatiblePluginInputEvent extends PluginDomEventBase<CompatiblePluginEventType.Input, InputEvent> {
+}
+
+    /**
+ * This interface represents a PluginEvent wrapping native scroll event
+ */
+interface CompatiblePluginScrollEvent extends PluginScrollEventData, PluginDomEventBase<CompatiblePluginEventType.Scroll, UIEvent> {
+}
+
+    /**
+ * Data of PluginScrollEvent
+ */
+interface PluginScrollEventData {
+    /**
+     * Current scroll container that triggers this scroll event
+     */
     scrollContainer: HTMLElement;
 }
 
+    /**
+ * Data of PluginMouseUpEvent
+ */
+interface PluginMouseUpEventData {
+    /**
+     * Whether this is a mouse click event (mouse up and down on the same position)
+     */
+    isClicking?: boolean;
+}
+
+    /**
+ * Data of PluginContextMenuEvent
+ */
+interface PluginContextMenuEventData {
+    /**
+     * A callback array to let editor retrieve context menu item related to this event.
+     * Plugins can add their own getter callback to this array,
+     * items from each getter will be separated by a splitter item represented by null
+     */
+    items: any[];
+}
+
     /**
  * Editor plugin event interface
  */
-type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent;
+type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent | CompatibleBeforeCutCopyEvent | CompatibleBeforeDisposeEvent | CompatibleBeforePasteEvent | CompatibleBeforeSetContentEvent | CompatibleContentChangedEvent | CompatibleEditImageEvent | CompatibleEditorReadyEvent | CompatibleEntityOperationEvent | CompatibleExtractContentWithDomEvent | CompatiblePendingFormatStateChangedEvent | CompatiblePluginDomEvent | CompatibleEnterShadowEditEvent | CompatibleLeaveShadowEditEvent | CompatibleZoomChangedEvent;
 
     /**
  * A type to extract data part of a plugin event type. Data part is the plugin event without eventType field.
@@ -4506,7 +4707,19 @@ type PluginEventFromTypeGeneric<E extends PluginEvent, T extends PluginEventType
     /**
  * A plugin triggered right after editor has entered Shadow Edit mode
  */
-interface EnterShadowEditEvent extends BasePluginEvent<PluginEventType.EnteredShadowEdit> {
+interface EnterShadowEditEvent extends EnterShadowEditEventData, BasePluginEvent<PluginEventType.EnteredShadowEdit> {
+}
+
+    /**
+ * A plugin triggered right before editor leave Shadow Edit mode
+ */
+interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.LeavingShadowEdit> {
+}
+
+    /**
+ * Data of EnterShadowEditEvent
+ */
+interface EnterShadowEditEventData {
     /**
      * The document fragment of original editor content
      */
@@ -4517,10 +4730,16 @@ interface EnterShadowEditEvent extends BasePluginEvent<PluginEventType.EnteredSh
     selectionPath: SelectionPath;
 }
 
+    /**
+ * A plugin triggered right after editor has entered Shadow Edit mode
+ */
+interface CompatibleEnterShadowEditEvent extends EnterShadowEditEventData, BasePluginEvent<CompatiblePluginEventType.EnteredShadowEdit> {
+}
+
     /**
  * A plugin triggered right before editor leave Shadow Edit mode
  */
-interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.LeavingShadowEdit> {
+interface CompatibleLeaveShadowEditEvent extends BasePluginEvent<CompatiblePluginEventType.LeavingShadowEdit> {
 }
 
     /**
@@ -4528,7 +4747,13 @@ interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.LeavingSh
  * Plugins can handle this event when they need to do something for zoom changing.
  *
  */
-interface ZoomChangedEvent extends BasePluginEvent<PluginEventType.ZoomChanged> {
+interface ZoomChangedEvent extends ZoomChangedEventData, BasePluginEvent<PluginEventType.ZoomChanged> {
+}
+
+    /**
+ * Data of ZoomChangedEvent
+ */
+interface ZoomChangedEventData {
     /**
      * Zoom scale value before this change
      */
@@ -4539,6 +4764,14 @@ interface ZoomChangedEvent extends BasePluginEvent<PluginEventType.ZoomChanged>
     newZoomScale: number;
 }
 
+    /**
+ * Represents an event object triggered from Editor.setZoomScale() API.
+ * Plugins can handle this event when they need to do something for zoom changing.
+ *
+ */
+interface CompatibleZoomChangedEvent extends ZoomChangedEventData, BasePluginEvent<CompatiblePluginEventType.ZoomChanged> {
+}
+
     /**
  * This refers to a "content block" in editor that serves as a content parsing boundary
  * It is most those html block like tags, i.e. &lt;p&gt;, &lt;div&gt;, &lt;li&gt;, &lt;td&gt; etc.
@@ -4651,6 +4884,16 @@ interface CustomData {
     disposer?: (value: any) => void;
 }
 
+    /**
+ * Property that is going to store additional data related to the Content Changed Event
+ */
+interface ContentChangedData {
+    /**
+     * Optional property to store the format api name when using ChangeSource.Format
+     */
+    formatApiName?: string;
+}
+
     /**
  * Default format settings
  */
@@ -5862,8 +6105,9 @@ interface IEditor {
      * @param changeSource The change source to use when fire ContentChangedEvent. When the value is not null,
      * a ContentChangedEvent will be fired with change source equal to this value
      * @param canUndoByBackspace True if this action can be undone when user presses Backspace key (aka Auto Complete).
+     * @param additionalData Optional parameter to provide additional data related to the ContentChanged Event.
      */
-    addUndoSnapshot(callback?: (start: NodePosition, end: NodePosition) => any, changeSource?: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace?: boolean): void;
+    addUndoSnapshot(callback?: (start: NodePosition, end: NodePosition) => any, changeSource?: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace?: boolean, additionalData?: ContentChangedData): void;
     /**
      * Whether there is an available undo/redo snapshot
      */
@@ -6245,8 +6489,9 @@ interface EditorCore extends PluginState  {
  * @param callback The editing callback, accepting current selection start and end position, returns an optional object used as the data field of ContentChangedEvent.
  * @param changeSource The ChangeSource string of ContentChangedEvent. @default ChangeSource.Format. Set to null to avoid triggering ContentChangedEvent
  * @param canUndoByBackspace True if this action can be undone when user press Backspace key (aka Auto Complete).
+ * @param additionalData Optional parameter to provide additional data related to the ContentChanged Event.
  */
-type AddUndoSnapshot = (core: EditorCore, callback: (start: NodePosition, end: NodePosition) => any, changeSource: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace: boolean) => void;
+type AddUndoSnapshot = (core: EditorCore, callback: (start: NodePosition, end: NodePosition) => any, changeSource: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace: boolean, additionalData?: ContentChangedData) => void;
 
     /**
  * Attach a DOM event to the editor content DIV
@@ -9236,8 +9481,6 @@ class Paste implements EditorPlugin  {
  * - Apply selected item in picker
  *
  * PickerPlugin doesn't provide any UI, it just wraps related DOM events and invoke callback functions.
- * To show a picker UI, you need to build your own UI component. Please reference to
- * https://github.com/microsoft/roosterjs/tree/master/demo/scripts/controls/samplepicker
  */
 class PickerPlugin<T extends PickerDataProvider = PickerDataProvider> implements EditorPlugin  {
     readonly dataProvider: T;