roosterjs 8.25.0 → 8.26.0

package/dist/rooster-amd.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
 
@@ -337,6 +337,7 @@ export function applyTextStyle(container: Node, styler: (node: HTMLElement, isIn
  * @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
@@ -345,7 +346,7 @@ export function applyTextStyle(container: Node, styler: (node: HTMLElement, isIn
  *   When set to undefined, it means can't retrieve HTML string, there may be HTML string but direct retrieving is
  *   not supported by browser.
  */
-export function extractClipboardEvent(event: ClipboardEvent, callback: (clipboardData: ClipboardData) => void, options?: ExtractClipboardEventOption): void;
+export function extractClipboardEvent(event: ClipboardEvent, callback: (clipboardData: ClipboardData) => void, options?: ExtractClipboardEventOption, rangeBeforePaste?: Range): void;
 
 /**
  * Extract clipboard items to be a ClipboardData object for IE
@@ -2560,7 +2561,7 @@ export function toggleListType(editor: IEditor, listType: ListType | CompatibleL
 /**
  * Split selection into regions, and perform a block-wise formatting action for each region.
  */
-export function blockFormat(editor: IEditor, callback: (region: Region, start: NodePosition, end: NodePosition, chains: VListChain[]) => void, beforeRunCallback?: () => boolean): void;
+export 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
@@ -4207,7 +4208,13 @@ export const enum DefinitionType {
 /**
  * Provides a chance for plugin to change the content before it is copied from editor.
  */
-export interface BeforeCutCopyEvent extends BasePluginEvent<PluginEventType.BeforeCutCopy> {
+export interface BeforeCutCopyEvent extends BeforeCutCopyEventData, BasePluginEvent<PluginEventType.BeforeCutCopy> {
+}
+
+/**
+ * Data of BeforeCutCopyEvent
+ */
+export interface BeforeCutCopyEventData {
     /**
      * Raw DOM event
      */
@@ -4226,6 +4233,12 @@ export interface BeforeCutCopyEvent extends BasePluginEvent<PluginEventType.Befo
     isCut: boolean;
 }
 
+/**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+export interface CompatibleBeforeCutCopyEvent extends BeforeCutCopyEventData, BasePluginEvent<CompatiblePluginEventType.BeforeCutCopy> {
+}
+
 /**
  * Editor plugin event interface
  */
@@ -4253,7 +4266,19 @@ export interface BeforeDisposeEvent extends BasePluginEvent<PluginEventType.Befo
 /**
  * Provides a chance for plugin to change the content before it is pasted into editor.
  */
-export interface BeforePasteEvent extends BasePluginEvent<PluginEventType.BeforePaste> {
+export interface CompatibleBeforeDisposeEvent extends BasePluginEvent<CompatiblePluginEventType.BeforeDispose> {
+}
+
+/**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+export interface BeforePasteEvent extends BeforePasteEventData, BasePluginEvent<PluginEventType.BeforePaste> {
+}
+
+/**
+ * Data of BeforePasteEvent
+ */
+export interface BeforePasteEventData {
     /**
      * An object contains all related data for pasting
      */
@@ -4280,21 +4305,46 @@ export interface BeforePasteEvent extends BasePluginEvent<PluginEventType.Before
     htmlAttributes: Record<string, string>;
 }
 
+/**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+export 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.
  */
-export interface BeforeSetContentEvent extends BasePluginEvent<PluginEventType.BeforeSetContent> {
+export interface BeforeSetContentEvent extends BeforeSetContentEventData, BasePluginEvent<PluginEventType.BeforeSetContent> {
+}
+
+/**
+ * Data of BeforeSetContentEvent
+ */
+export 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.
+ */
+export interface CompatibleBeforeSetContentEvent extends BeforeSetContentEventData, BasePluginEvent<CompatiblePluginEventType.BeforeSetContent> {
+}
+
 /**
  * Represents a change to the editor made by another plugin
  */
-export interface ContentChangedEvent extends BasePluginEvent<PluginEventType.ContentChanged> {
+export interface ContentChangedEvent extends ContentChangedEventData, BasePluginEvent<PluginEventType.ContentChanged> {
+}
+
+/**
+ * Data of ContentChangedEvent
+ */
+export interface ContentChangedEventData {
     /**
      * Source of the change
      */
@@ -4303,13 +4353,26 @@ export interface ContentChangedEvent extends BasePluginEvent<PluginEventType.Con
      * Optional related data
      */
     data?: any;
+    additionalData?: ContentChangedData;
+}
+
+/**
+ * Represents a change to the editor made by another plugin
+ */
+export 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
  */
-export interface EditImageEvent extends BasePluginEvent<PluginEventType.EditImage> {
+export interface EditImageEvent extends EditImageEventData, BasePluginEvent<PluginEventType.EditImage> {
+}
+
+/**
+ * Data of EditImageEvent
+ */
+export interface EditImageEventData {
     /**
      * The image element that is being changed
      */
@@ -4330,17 +4393,36 @@ export interface EditImageEvent extends BasePluginEvent<PluginEventType.EditImag
     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
+ */
+export interface CompatibleEditImageEvent extends EditImageEventData, BasePluginEvent<CompatiblePluginEventType.EditImage> {
+}
+
 /**
  * Provides a chance for plugin to change the content before it is pasted into editor.
  */
 export interface EditorReadyEvent extends BasePluginEvent<PluginEventType.EditorReady> {
 }
 
+/**
+ * Provides a chance for plugin to change the content before it is pasted into editor.
+ */
+export 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
  */
-export interface EntityOperationEvent extends BasePluginEvent<PluginEventType.EntityOperation> {
+export interface EntityOperationEvent extends EntityOperationEventData, BasePluginEvent<PluginEventType.EntityOperation> {
+}
+
+/**
+ * Data of EntityOperationEvent
+ */
+export interface EntityOperationEventData {
     /**
      * Operation to this entity
      */
@@ -4367,13 +4449,26 @@ export interface EntityOperationEvent extends BasePluginEvent<PluginEventType.En
     contentForShadowEntity?: DocumentFragment;
 }
 
+/**
+ * Provide a chance for plugins to handle entity related events.
+ * See enum EntityOperation for more details about each operation
+ */
+export 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
  */
-export interface ExtractContentWithDomEvent extends BasePluginEvent<PluginEventType.ExtractContentWithDom> {
+export interface ExtractContentWithDomEvent extends ExtractContentWithDomEventData, BasePluginEvent<PluginEventType.ExtractContentWithDom> {
+}
+
+/**
+ * Data of ExtractContentWithDomEvent
+ */
+export interface ExtractContentWithDomEventData {
     /**
      * Cloned root element of editor
      * Plugin can change this DOM tree to clean up the markups it added before
@@ -4381,6 +4476,15 @@ export interface ExtractContentWithDomEvent extends BasePluginEvent<PluginEventT
     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
+ */
+export interface CompatibleExtractContentWithDomEvent extends ExtractContentWithDomEventData, BasePluginEvent<CompatiblePluginEventType.ExtractContentWithDom> {
+}
+
 /**
  * An event fired when pending format state (bold, italic, underline, ... with collapsed selection) is changed
  */
@@ -4388,6 +4492,13 @@ export interface PendingFormatStateChangedEvent extends BasePluginEvent<PluginEv
     formatState: PendableFormatState;
 }
 
+/**
+ * An event fired when pending format state (bold, italic, underline, ... with collapsed selection) is changed
+ */
+export interface CompatiblePendingFormatStateChangedEvent extends BasePluginEvent<CompatiblePluginEventType.PendingFormatStateChanged> {
+    formatState: PendableFormatState;
+}
+
 /**
  * This represents a PluginEvent wrapping native browser event
  */
@@ -4409,13 +4520,7 @@ export interface PluginCompositionEvent extends PluginDomEventBase<PluginEventTy
 /**
  * This interface represents a PluginEvent wrapping native ContextMenu event
  */
-export 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[];
+export interface PluginContextMenuEvent extends PluginContextMenuEventData, PluginDomEventBase<PluginEventType.ContextMenu, MouseEvent> {
 }
 
 /**
@@ -4455,11 +4560,7 @@ export interface PluginMouseDownEvent extends PluginDomEventBase<PluginEventType
 /**
  * This interface represents a PluginEvent wrapping native MouseUp event
  */
-export interface PluginMouseUpEvent extends PluginDomEventBase<PluginEventType.MouseUp, MouseEvent> {
-    /**
-     * Whether this is a mouse click event (mouse up and down on the same position)
-     */
-    isClicking?: boolean;
+export interface PluginMouseUpEvent extends PluginMouseUpEventData, PluginDomEventBase<PluginEventType.MouseUp, MouseEvent> {
 }
 
 /**
@@ -4471,14 +4572,114 @@ export interface PluginInputEvent extends PluginDomEventBase<PluginEventType.Inp
 /**
  * This interface represents a PluginEvent wrapping native scroll event
  */
-export interface PluginScrollEvent extends PluginDomEventBase<PluginEventType.Scroll, UIEvent> {
+export interface PluginScrollEvent extends PluginScrollEventData, PluginDomEventBase<PluginEventType.Scroll, UIEvent> {
+}
+
+/**
+ * This represents a PluginEvent wrapping native browser event
+ */
+export type CompatiblePluginDomEvent = CompatiblePluginCompositionEvent | CompatiblePluginMouseEvent | CompatiblePluginKeyboardEvent | CompatiblePluginInputEvent | CompatiblePluginScrollEvent;
+
+/**
+ * This interface represents a PluginEvent wrapping native CompositionEnd event
+ */
+export interface CompatiblePluginCompositionEvent extends PluginDomEventBase<CompatiblePluginEventType.CompositionEnd, CompositionEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native ContextMenu event
+ */
+export interface CompatiblePluginContextMenuEvent extends PluginContextMenuEventData, PluginDomEventBase<CompatiblePluginEventType.ContextMenu, MouseEvent> {
+}
+
+/**
+ * The interface represents a PluginEvent wrapping native Keyboard event
+ */
+export type CompatiblePluginKeyboardEvent = CompatiblePluginKeyDownEvent | CompatiblePluginKeyPressEvent | CompatiblePluginKeyUpEvent;
+
+/**
+ * This interface represents a PluginEvent wrapping native KeyDown event
+ */
+export interface CompatiblePluginKeyDownEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyDown, KeyboardEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native KeyPress event
+ */
+export interface CompatiblePluginKeyPressEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyPress, KeyboardEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native KeyUp event
+ */
+export interface CompatiblePluginKeyUpEvent extends PluginDomEventBase<CompatiblePluginEventType.KeyUp, KeyboardEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native Mouse event
+ */
+export type CompatiblePluginMouseEvent = CompatiblePluginMouseDownEvent | CompatiblePluginMouseUpEvent | CompatiblePluginContextMenuEvent;
+
+/**
+ * This interface represents a PluginEvent wrapping native MouseDown event
+ */
+export interface CompatiblePluginMouseDownEvent extends PluginDomEventBase<CompatiblePluginEventType.MouseDown, MouseEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native MouseUp event
+ */
+export interface CompatiblePluginMouseUpEvent extends PluginMouseUpEventData, PluginDomEventBase<CompatiblePluginEventType.MouseUp, MouseEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native input / textinput event
+ */
+export interface CompatiblePluginInputEvent extends PluginDomEventBase<CompatiblePluginEventType.Input, InputEvent> {
+}
+
+/**
+ * This interface represents a PluginEvent wrapping native scroll event
+ */
+export interface CompatiblePluginScrollEvent extends PluginScrollEventData, PluginDomEventBase<CompatiblePluginEventType.Scroll, UIEvent> {
+}
+
+/**
+ * Data of PluginScrollEvent
+ */
+export interface PluginScrollEventData {
+    /**
+     * Current scroll container that triggers this scroll event
+     */
     scrollContainer: HTMLElement;
 }
 
+/**
+ * Data of PluginMouseUpEvent
+ */
+export interface PluginMouseUpEventData {
+    /**
+     * Whether this is a mouse click event (mouse up and down on the same position)
+     */
+    isClicking?: boolean;
+}
+
+/**
+ * Data of PluginContextMenuEvent
+ */
+export 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
  */
-export type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent;
+export 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.
@@ -4505,7 +4706,19 @@ export type PluginEventFromTypeGeneric<E extends PluginEvent, T extends PluginEv
 /**
  * A plugin triggered right after editor has entered Shadow Edit mode
  */
-export interface EnterShadowEditEvent extends BasePluginEvent<PluginEventType.EnteredShadowEdit> {
+export interface EnterShadowEditEvent extends EnterShadowEditEventData, BasePluginEvent<PluginEventType.EnteredShadowEdit> {
+}
+
+/**
+ * A plugin triggered right before editor leave Shadow Edit mode
+ */
+export interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.LeavingShadowEdit> {
+}
+
+/**
+ * Data of EnterShadowEditEvent
+ */
+export interface EnterShadowEditEventData {
     /**
      * The document fragment of original editor content
      */
@@ -4516,10 +4729,16 @@ export interface EnterShadowEditEvent extends BasePluginEvent<PluginEventType.En
     selectionPath: SelectionPath;
 }
 
+/**
+ * A plugin triggered right after editor has entered Shadow Edit mode
+ */
+export interface CompatibleEnterShadowEditEvent extends EnterShadowEditEventData, BasePluginEvent<CompatiblePluginEventType.EnteredShadowEdit> {
+}
+
 /**
  * A plugin triggered right before editor leave Shadow Edit mode
  */
-export interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.LeavingShadowEdit> {
+export interface CompatibleLeaveShadowEditEvent extends BasePluginEvent<CompatiblePluginEventType.LeavingShadowEdit> {
 }
 
 /**
@@ -4527,7 +4746,13 @@ export interface LeaveShadowEditEvent extends BasePluginEvent<PluginEventType.Le
  * Plugins can handle this event when they need to do something for zoom changing.
  *
  */
-export interface ZoomChangedEvent extends BasePluginEvent<PluginEventType.ZoomChanged> {
+export interface ZoomChangedEvent extends ZoomChangedEventData, BasePluginEvent<PluginEventType.ZoomChanged> {
+}
+
+/**
+ * Data of ZoomChangedEvent
+ */
+export interface ZoomChangedEventData {
     /**
      * Zoom scale value before this change
      */
@@ -4538,6 +4763,14 @@ export interface ZoomChangedEvent extends BasePluginEvent<PluginEventType.ZoomCh
     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.
+ *
+ */
+export 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.
@@ -4650,6 +4883,16 @@ export interface CustomData {
     disposer?: (value: any) => void;
 }
 
+/**
+ * Property that is going to store additional data related to the Content Changed Event
+ */
+export interface ContentChangedData {
+    /**
+     * Optional property to store the format api name when using ChangeSource.Format
+     */
+    formatApiName?: string;
+}
+
 /**
  * Default format settings
  */
@@ -5861,8 +6104,9 @@ export 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
      */
@@ -6244,8 +6488,9 @@ export 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.
  */
-export type AddUndoSnapshot = (core: EditorCore, callback: (start: NodePosition, end: NodePosition) => any, changeSource: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace: boolean) => void;
+export 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
@@ -9235,8 +9480,6 @@ export 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
  */
 export class PickerPlugin<T extends PickerDataProvider = PickerDataProvider> implements EditorPlugin  {
     readonly dataProvider: T;