roosterjs 8.45.2 → 8.47.0

package/dist/rooster-amd.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.45.2)
+// Type definitions for roosterjs (Version 8.47.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -401,6 +401,19 @@ export function extractClipboardItems(items: DataTransferItem[], options?: Extra
  */
 export function extractClipboardItemsForIE(dataTransfer: DataTransfer, callback: (data: ClipboardData) => void, options?: ExtractClipboardItemsForIEOptions): void;
 
+/**
+ * Create a DocumentFragment for paste from a ClipboardData
+ * @param core The EditorCore object.
+ * @param clipboardData Clipboard data retrieved from clipboard
+ * @param position The position to paste to
+ * @param pasteAsText True to force use plain text as the content to paste, false to choose HTML or Image if any
+ * @param applyCurrentStyle True if apply format of current selection to the pasted content,
+ * @param pasteAsImage Whether to force paste as image
+ * @param event Event to trigger.
+ * false to keep original format
+ */
+export function createFragmentFromClipboardData(core: EditorCore, clipboardData: ClipboardData, position: NodePosition | null, pasteAsText: boolean, applyCurrentStyle: boolean, pasteAsImage: boolean, event: BeforePasteEvent): DocumentFragment;
+
 /**
  * Browser object contains browser and operating system information of current environment
  */
@@ -710,7 +723,8 @@ export function getInnerHTML(node: HTMLElement | DocumentFragment): string;
  * @param isBackgroundColor Whether set background color or text color
  * @param isDarkMode Whether current mode is dark mode. @default false
  * @param shouldAdaptTheFontColor Whether the font color needs to be adapted to be visible in a dark or bright background color. @default false
- * @param darkColorHandler An optional dark color handler object. When it is passed, we will use this handler to do variable-based dark color instead of original dataset base dark color
+ * @param darkColorHandler A dark color handler object. This is now required.
+ * We keep it optional only for backward compatibility. If it is not passed, color will not be set.
  */
 export function setColor(element: HTMLElement, color: string | ModeIndependentColor, isBackgroundColor: boolean, isDarkMode?: boolean, shouldAdaptTheFontColor?: boolean, darkColorHandler?: DarkColorHandler | null): void;
 
@@ -1781,8 +1795,7 @@ export function removeImportantStyleRule(element: HTMLElement, styleProperties:
  * Add global css styles
  * @param doc The document object
  * @param cssRule The css rule that must added to the selection
- * @param editorId Te id of the editor
- * @param styleId the ID of the style tag
+ * @param styleId The id of the style tag
  */
 export function setGlobalCssStyles(doc: Document, cssRule: string, styleId: string): void;
 
@@ -1945,6 +1958,14 @@ export function toArray<T extends Element>(collection: HTMLCollectionOf<T>): T[]
  */
 export function toArray<T>(array: readonly T[]): T[];
 
+/**
+ * This function tries to get the source of the Pasted content
+ * @param event the before paste event
+ * @param shouldConvertSingleImage Whether convert single image is enabled.
+ * @returns The Type of pasted content, if no type found will return {KnownSourceType.Default}
+ */
+export function getPasteSource(event: BeforePasteEvent, shouldConvertSingleImage: boolean): KnownPasteSourceType;
+
 /**
  * RoosterJs core editor class
  */
@@ -2093,7 +2114,7 @@ export class EditorBase<TEditorCore extends EditorCore, TEditorOptions extends E
      * Focus to this editor, the selection was restored to where it was before, no unexpected scroll.
      */
     focus(): void;
-    select(arg1: Range | SelectionRangeEx | NodePosition | Node | SelectionPath | null, arg2?: NodePosition | number | PositionType | TableSelection, arg3?: Node, arg4?: number | PositionType): boolean;
+    select(arg1: Range | SelectionRangeEx | NodePosition | Node | SelectionPath | null, arg2?: NodePosition | number | PositionType | TableSelection | null, arg3?: Node, arg4?: number | PositionType): boolean;
     /**
      * Get current focused position. Return null if editor doesn't have focus at this time.
      */
@@ -2282,9 +2303,9 @@ export class EditorBase<TEditorCore extends EditorCore, TEditorOptions extends E
      */
     transformToDarkColor(node: Node): void;
     /**
-     * Get a darkColorHandler object for this editor. It will return null if experimental feature "VariableBasedDarkColor" is not enabled
+     * Get a darkColorHandler object for this editor.
      */
-    getDarkColorHandler(): DarkColorHandler | null;
+    getDarkColorHandler(): DarkColorHandler;
     /**
      * Make the editor in "Shadow Edit" mode.
      * In Shadow Edit mode, all format change will finally be ignored.
@@ -2435,8 +2456,11 @@ export function getElementBasedFormatState(editor: IEditor, event?: PluginEvent)
  * If isBlock is true, entity will be insert below this position
  * @param insertToRegionRoot @optional When pass true, insert the entity at the root level of current region.
  * Parent nodes will be split if need
+ * @param focusAfterEntity @optional When pass true, focus will be moved next to the entity. For inline entity,
+ * focus will be after right after the entity (and the delimiter if exist). For block entity, focus will be in
+ * the new empty line below the entity
  */
-export function insertEntity(editor: IEditor, type: string, contentNode: Node, isBlock: boolean, isReadonly: boolean, position?: NodePosition | ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd, insertToRegionRoot?: boolean): Entity;
+export function insertEntity(editor: IEditor, type: string, contentNode: Node, isBlock: boolean, isReadonly: boolean, position?: NodePosition | ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | CompatibleContentPosition.Begin | CompatibleContentPosition.End | CompatibleContentPosition.DomEnd, insertToRegionRoot?: boolean, focusAfterEntity?: boolean): Entity;
 
 /**
  * Insert an image to editor at current selection
@@ -3519,6 +3543,7 @@ export const enum ContentPosition {
 }
 
 /**
+ * @deprecated
  * Constants string for dataset names used by dark mode
  */
 export const enum DarkModeDatasetNames {
@@ -3737,13 +3762,21 @@ export const enum ExperimentalFeatures {
      */
     ImageSelection = "ImageSelection",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     * @deprecated this feature is always enabled
+     * Use variable-based dark mode solution rather than dataset-based solution.
+     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
+     * if you need them work for dark mode
      */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
+    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
+     * @deprecated this feature is always enabled
      * Align list elements elements to left, center and right using setAlignment API
      */
     ListItemAlignment = "ListItemAlignment",
+    /**
+     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
@@ -3760,16 +3793,18 @@ export const enum ExperimentalFeatures {
      * the block element (In most case, the DIV element) so keep the block element clean.
      */
     DefaultFormatInSpan = "DefaultFormatInSpan",
-    /**
-     * Use variable-based dark mode solution rather than dataset-based solution.
-     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
-     * if you need them work for dark mode
-     */
-    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
     ReusableContentModel = "ReusableContentModel",
+    /**
+     * Handle keyboard editing event with Content Model
+     */
+    EditWithContentModel = "EditWithContentModel",
+    /**
+     * Apply default format on editor container
+     */
+    DefaultFormatOnContainer = "DefaultFormatOnContainer",
     /**
      * Delete table with Backspace key with the whole was selected with table selector
      */
@@ -3777,7 +3812,11 @@ export const enum ExperimentalFeatures {
     /**
      * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
      */
-    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters"
+    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
+    /**
+     * Paste with Content model
+     */
+    ContentModelPaste = "ContentModelPaste"
 }
 
 /**
@@ -4151,6 +4190,20 @@ export const enum KnownCreateElementDataIndex {
     EmptyLineFormatInSpan = 12
 }
 
+/**
+ * Represent the types of sources to handle in the Paste Plugin
+ */
+export const enum KnownPasteSourceType {
+    WordDesktop = 0,
+    ExcelDesktop = 1,
+    ExcelOnline = 2,
+    PowerPointDesktop = 3,
+    GoogleSheets = 4,
+    WacComponents = 5,
+    Default = 6,
+    SingleImage = 7
+}
+
 /**
  * Table format border
  */
@@ -4325,7 +4378,13 @@ export const enum PluginEventType {
      * EXPERIMENTAL FEATURE
      * Editor changed the selection.
      */
-    SelectionChanged = 22
+    SelectionChanged = 22,
+    /**
+     * EXPERIMENTAL FEATURE
+     * Editor content is about to be changed by keyboard event.
+     * This is only used by Content Model editing
+     */
+    BeforeKeyboardEditing = 23
 }
 
 /**
@@ -4520,6 +4579,28 @@ export const enum DefinitionType {
     Customize = 5
 }
 
+/**
+ * Enum for paste options
+ */
+export const enum PasteType {
+    /**
+     * Default paste behavior
+     */
+    Normal = 0,
+    /**
+     * Paste only the plain text
+     */
+    AsPlainText = 1,
+    /**
+     * Apply the current style to pasted content
+     */
+    MergeFormat = 2,
+    /**
+     * If there is a image uri in the clipboard, paste the content as image element
+     */
+    AsImage = 3
+}
+
 /**
  * Provides a chance for plugin to change the content before it is copied from editor.
  */
@@ -4618,6 +4699,10 @@ export interface BeforePasteEventData {
      * Attributes of the root "HTML" tag
      */
     htmlAttributes: Record<string, string>;
+    /**
+     * Paste type option (as plain text, merge format, normal, as image)
+     */
+    readonly pasteType: PasteType | CompatiblePasteType;
 }
 
 /**
@@ -5008,7 +5093,7 @@ export interface PluginContextMenuEventData {
 /**
  * Editor plugin event interface
  */
-export type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent | SelectionChangedEvent | CompatibleBeforeCutCopyEvent | CompatibleBeforeDisposeEvent | CompatibleBeforePasteEvent | CompatibleBeforeSetContentEvent | CompatibleContentChangedEvent | CompatibleEditImageEvent | CompatibleEditorReadyEvent | CompatibleEntityOperationEvent | CompatibleExtractContentWithDomEvent | CompatiblePendingFormatStateChangedEvent | CompatiblePluginDomEvent | CompatibleEnterShadowEditEvent | CompatibleLeaveShadowEditEvent | CompatibleZoomChangedEvent | CompatibleSelectionChangedEvent;
+export type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent | SelectionChangedEvent | BeforeKeyboardEditingEvent | CompatibleBeforeCutCopyEvent | CompatibleBeforeDisposeEvent | CompatibleBeforePasteEvent | CompatibleBeforeSetContentEvent | CompatibleContentChangedEvent | CompatibleEditImageEvent | CompatibleEditorReadyEvent | CompatibleEntityOperationEvent | CompatibleExtractContentWithDomEvent | CompatiblePendingFormatStateChangedEvent | CompatiblePluginDomEvent | CompatibleEnterShadowEditEvent | CompatibleLeaveShadowEditEvent | CompatibleZoomChangedEvent | CompatibleSelectionChangedEvent | CompatibleBeforeKeyboardEditingEvent;
 
 /**
  * A type to extract data part of a plugin event type. Data part is the plugin event without eventType field.
@@ -5122,6 +5207,28 @@ export interface SelectionChangedEventData {
 export interface CompatibleSelectionChangedEvent extends SelectionChangedEventData, BasePluginEvent<CompatiblePluginEventType.SelectionChanged> {
 }
 
+/**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+export interface BeforeKeyboardEditingEvent extends BeforeKeyboardEditingData, BasePluginEvent<PluginEventType.BeforeKeyboardEditing> {
+}
+
+/**
+ * Data of BeforeKeyboardEditing
+ */
+export interface BeforeKeyboardEditingData {
+    /**
+     * Raw DOM event
+     */
+    rawEvent: KeyboardEvent;
+}
+
+/**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+export interface CompatibleBeforeKeyboardEditingEvent extends BeforeKeyboardEditingData, BasePluginEvent<CompatiblePluginEventType.BeforeKeyboardEditing> {
+}
+
 /**
  * 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.
@@ -5637,7 +5744,7 @@ export interface InsertOptionBase {
  * The "basic" insertNode related ContentPositions that require no additional parameters to use.
  */
 export interface InsertOptionBasic extends InsertOptionBase  {
-    position: ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | ContentPosition.Outside | ContentPosition.SelectionStart;
+    position: ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | ContentPosition.Outside | ContentPosition.SelectionStart | CompatibleContentPosition.Begin | CompatibleContentPosition.End | CompatibleContentPosition.DomEnd | CompatibleContentPosition.Outside | CompatibleContentPosition.SelectionStart;
 }
 
 /**
@@ -6071,7 +6178,7 @@ export interface HtmlSanitizerOptions {
      *
      * For other unknown tags, we will respect the value of unknownTagReplacement with the same meaning
      */
-    additionalTagReplacements?: Record<string, string>;
+    additionalTagReplacements?: Record<string, string | null>;
     /**
      * Allowed HTML attributes in addition to default attributes, in lower case
      */
@@ -6453,9 +6560,9 @@ export interface IEditor {
     /**
      * Select content using the Table Selection
      * @param table to select
-     * @param coordinates first and last cell of the range
+     * @param coordinates first and last cell of the range, if null is provided will remove the selection on the table
      */
-    select(table: HTMLTableElement, coordinates: TableSelection): boolean;
+    select(table: HTMLTableElement, coordinates: TableSelection | null): boolean;
     /**
      * Select content SelectionRangeEx
      * @param rangeEx SelectionRangeEx object to specify what to select
@@ -6664,9 +6771,9 @@ export interface IEditor {
      */
     transformToDarkColor(node: Node): void;
     /**
-     * Get a darkColorHandler object for this editor. It will return null if experimental feature "VariableBasedDarkColor" is not enabled
+     * Get a darkColorHandler object for this editor.
      */
-    getDarkColorHandler(): DarkColorHandler | null;
+    getDarkColorHandler(): DarkColorHandler;
     /**
      * Make the editor in "Shadow Edit" mode.
      * In Shadow Edit mode, all format change will finally be ignored.
@@ -6999,7 +7106,7 @@ export interface EditorCore extends PluginState  {
      * Dark model handler for the editor, used for variable-based solution.
      * If keep it null, editor will still use original dataset-based dark mode solution.
      */
-    darkColorHandler?: DarkColorHandler;
+    darkColorHandler: DarkColorHandler;
 }
 
 /**
@@ -7123,7 +7230,7 @@ export interface CoreApiMap {
      * There are a bunch of allowed combination of parameters. See IEditor.select for more details
      * @param core The editor core object
      * @param arg1 A DOM Range, or SelectionRangeEx, or NodePosition, or Node, or Selection Path
-     * @param arg2 (optional) A NodePosition, or an offset number, or a PositionType, or a TableSelection
+     * @param arg2 (optional) A NodePosition, or an offset number, or a PositionType, or a TableSelection, or null
      * @param arg3 (optional) A Node
      * @param arg4 (optional) An offset number, or a PositionType
      */
@@ -7281,11 +7388,11 @@ export type RestoreUndoSnapshot = (core: EditorCore, step: number) => void;
  * There are a bunch of allowed combination of parameters. See IEditor.select for more details
  * @param core The editor core object
  * @param arg1 A DOM Range, or SelectionRangeEx, or NodePosition, or Node, or Selection Path
- * @param arg2 (optional) A NodePosition, or an offset number, or a PositionType, or a TableSelection
+ * @param arg2 (optional) A NodePosition, or an offset number, or a PositionType, or a TableSelection, or null
  * @param arg3 (optional) A Node
  * @param arg4 (optional) An offset number, or a PositionType
  */
-export type Select = (core: EditorCore, arg1: Range | SelectionRangeEx | NodePosition | Node | SelectionPath | null, arg2?: NodePosition | number | PositionType | TableSelection, arg3?: Node, arg4?: number | PositionType) => boolean;
+export type Select = (core: EditorCore, arg1: Range | SelectionRangeEx | NodePosition | Node | SelectionPath | null, arg2?: NodePosition | number | PositionType | TableSelection | null, arg3?: Node, arg4?: number | PositionType) => boolean;
 
 /**
  * Change the editor selection to the given range
@@ -8375,13 +8482,21 @@ export enum CompatibleExperimentalFeatures {
      */
     ImageSelection = "ImageSelection",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     * @deprecated this feature is always enabled
+     * Use variable-based dark mode solution rather than dataset-based solution.
+     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
+     * if you need them work for dark mode
      */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
+    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
+     * @deprecated this feature is always enabled
      * Align list elements elements to left, center and right using setAlignment API
      */
     ListItemAlignment = "ListItemAlignment",
+    /**
+     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
@@ -8398,16 +8513,18 @@ export enum CompatibleExperimentalFeatures {
      * the block element (In most case, the DIV element) so keep the block element clean.
      */
     DefaultFormatInSpan = "DefaultFormatInSpan",
-    /**
-     * Use variable-based dark mode solution rather than dataset-based solution.
-     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
-     * if you need them work for dark mode
-     */
-    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
     ReusableContentModel = "ReusableContentModel",
+    /**
+     * Handle keyboard editing event with Content Model
+     */
+    EditWithContentModel = "EditWithContentModel",
+    /**
+     * Apply default format on editor container
+     */
+    DefaultFormatOnContainer = "DefaultFormatOnContainer",
     /**
      * Delete table with Backspace key with the whole was selected with table selector
      */
@@ -8415,7 +8532,11 @@ export enum CompatibleExperimentalFeatures {
     /**
      * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
      */
-    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters"
+    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
+    /**
+     * Paste with Content model
+     */
+    ContentModelPaste = "ContentModelPaste"
 }
 
 /**
@@ -8518,7 +8639,35 @@ export enum CompatiblePluginEventType {
      * EXPERIMENTAL FEATURE
      * Editor changed the selection.
      */
-    SelectionChanged = 22
+    SelectionChanged = 22,
+    /**
+     * EXPERIMENTAL FEATURE
+     * Editor content is about to be changed by keyboard event.
+     * This is only used by Content Model editing
+     */
+    BeforeKeyboardEditing = 23
+}
+
+/**
+ * Enum for paste options
+ */
+export enum CompatiblePasteType {
+    /**
+     * Default paste behavior
+     */
+    Normal = 0,
+    /**
+     * Paste only the plain text
+     */
+    AsPlainText = 1,
+    /**
+     * Apply the current style to pasted content
+     */
+    MergeFormat = 2,
+    /**
+     * If there is a image uri in the clipboard, paste the content as image element
+     */
+    AsImage = 3
 }
 
 /**
@@ -9051,6 +9200,7 @@ export enum CompatibleContentType {
 }
 
 /**
+ * @deprecated
  * Constants string for dataset names used by dark mode
  */
 export enum CompatibleDarkModeDatasetNames {
@@ -9509,6 +9659,20 @@ export enum CompatibleKnownCreateElementDataIndex {
     EmptyLineFormatInSpan = 12
 }
 
+/**
+ * Represent the types of sources to handle in the Paste Plugin
+ */
+export enum CompatibleKnownPasteSourceType {
+    WordDesktop = 0,
+    ExcelDesktop = 1,
+    ExcelOnline = 2,
+    PowerPointDesktop = 3,
+    GoogleSheets = 4,
+    WacComponents = 5,
+    Default = 6,
+    SingleImage = 7
+}
+
 /**
  * Type of list (numbering or bullet)
  */
@@ -10404,15 +10568,8 @@ export class Watermark implements EditorPlugin  {
  */
 export class TableCellSelection implements EditorPlugin  {
     private editor;
-    private lastTarget;
-    private firstTarget;
-    private tableRange;
-    private tableSelection;
-    private startedSelection;
-    private vTable;
-    private firstTable;
-    private targetTable;
-    private preventKeyUp;
+    private state;
+    private shadowEditCoordinatesBackup;
     constructor();
     /**
      * Get a friendly name of  this plugin
@@ -10432,37 +10589,8 @@ export class TableCellSelection implements EditorPlugin  {
      * @param event PluginEvent object
      */
     onPluginEvent(event: PluginEvent): void;
-    /**
-     * Handle Scroll Event and mantains the selection range,
-     * Since when we scroll the cursor does not trigger the on Mouse Move event
-     * The table selection gets removed.
-     */
-    private handleScrollEvent;
-    /**
-     * Handles the on key event.
-     * @param event the plugin event
-     */
-    private handleKeyDownEvent;
-    private handleKeyUpEvent;
-    private handleKeySelectionInsideTable;
-    private handleMouseDownEvent;
-    private onMouseMove;
-    private onMouseUp;
-    private restoreSelection;
-    /**
-     * @internal
-     * Public only for unit testing
-     * @param event mouse event
-     */
-    selectionInsideTableMouseMove(event: MouseEvent): void;
-    private removeMouseUpEventListener;
-    private clearState;
-    private getNextTD;
-    private prepareSelection;
-    private setData;
-    private isAfter;
-    private shouldConvertToTableSelection;
-    selectTable(): void;
+    private handleLeavingShadowEdit;
+    private handleEnteredShadowEdit;
 }
 
 /**