roosterjs 8.30.2 → 8.31.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.30.2)
+// Type definitions for roosterjs (Version 8.31.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -736,15 +736,12 @@ class VTable {
      * Current column index
      */
     col: number | undefined;
-    /**
-     * Selected range of cells with the coordinates of the first and last cell selected.
-     */
-    selection: TableSelection | null;
     /**
      * Current format of the table
      */
     formatInfo: Required<TableFormat> | null;
     private trs;
+    private tableSelection;
     /**
      * Create a new instance of VTable object using HTML TABLE or TD node
      * @param node The HTML Table or TD node
@@ -752,12 +749,18 @@ class VTable {
      * @param zoomScale When the table is under a zoomed container, pass in the zoom scale here
      */
     constructor(node: HTMLTableElement | HTMLTableCellElement, normalizeSize?: boolean, zoomScale?: number | SizeTransformer);
+    /**
+     * Selected range of cells with the coordinates of the first and last cell selected.
+     */
+    get selection(): TableSelection | null;
+    set selection(value: TableSelection | null);
     /**
      * Write the virtual table back to DOM tree to represent the change of VTable
      * @param skipApplyFormat Do not reapply table format when write back.
      * Only use this parameter when you are pretty sure there is no format or table structure change during the process.
      */
     writeBack(skipApplyFormat?: boolean): void;
+    private recalculateCellHeight;
     /**
      * Apply the given table format to this virtual table
      * @param format Table format to apply
@@ -775,6 +778,8 @@ class VTable {
     edit(operation: TableOperation | CompatibleTableOperation): void;
     setAlignmentToSelectedCells(firstRow: number, lastRow: number, firstColumn: number, lastColumn: number, alignmentType: string, isVertical?: boolean): void;
     private mergeCells;
+    private isEmptyCell;
+    private mergeCellContents;
     /**
      * Loop each cell of current column and invoke a callback function
      * @param callback The callback function to invoke
@@ -1613,7 +1618,7 @@ function getEntitySelector(type?: string, id?: string): string;
  * @param key Cache key string, need to be unique
  * @param getter Getter function to get the object when it is not in cache yet
  */
-function cacheGetEventData<T>(event: PluginEvent, key: string, getter: () => T): T;
+function cacheGetEventData<T>(event: PluginEvent | null, key: string, getter: () => T): T;
 
     /**
  * Clear a cached object by its key from an event object
@@ -1672,7 +1677,7 @@ function adjustInsertPosition(root: HTMLElement, nodeToInsert: Node, position: N
  * @param core The EditorCore object.
  * @param range The range to delete
  */
-function deleteSelectedContent(root: HTMLElement, range: Range): null;
+function deleteSelectedContent(root: HTMLElement, range: Range): NodePosition | null;
 
     /**
  * get block element's text content.
@@ -1859,7 +1864,7 @@ class Editor implements IEditor  {
      * @param node The node to create InlineElement
      * @returns The BlockElement result
      */
-    getBlockElementAtNode(node: Node): BlockElement;
+    getBlockElementAtNode(node: Node): BlockElement | null;
     contains(arg: Node | Range): boolean;
     queryElements(selector: string, scopeOrCallback?: QueryScope | CompatibleQueryScope | ((node: Node) => any), callback?: (node: Node) => any): HTMLElement[];
     /**
@@ -1905,7 +1910,7 @@ class Editor implements IEditor  {
     /**
      * Delete selected content
      */
-    deleteSelectedContent(): NodePosition;
+    deleteSelectedContent(): NodePosition | null;
     /**
      * Paste into editor using a clipboardData object
      * @param clipboardData Clipboard data retrieved from clipboard
@@ -1921,7 +1926,7 @@ class Editor implements IEditor  {
      * Default value is true
      * @returns current selection range, or null if editor never got focus before
      */
-    getSelectionRange(tryGetFromCache?: boolean): Range;
+    getSelectionRange(tryGetFromCache?: boolean): Range | null;
     /**
      * Get current selection range from Editor.
      * It does a live pull on the selection, if nothing retrieved, return whatever we have in cache.
@@ -1935,7 +1940,7 @@ class Editor implements IEditor  {
      * It does a live pull on the selection, if nothing retrieved, return whatever we have in cache.
      * @returns current selection path, or null if editor never got focus before
      */
-    getSelectionPath(): SelectionPath;
+    getSelectionPath(): SelectionPath | null;
     /**
      * Check if focus is in editor now
      * @returns true if focus is in editor, otherwise false
@@ -1945,11 +1950,11 @@ class Editor implements IEditor  {
      * Focus to this editor, the selection was restored to where it was before, no unexpected scroll.
      */
     focus(): void;
-    select(arg1: any, arg2?: any, arg3?: any, arg4?: any): boolean;
+    select(arg1: Range | NodePosition | Node | SelectionPath | HTMLTableElement | null, arg2?: NodePosition | number | PositionType | TableSelection, arg3?: Node, arg4?: number | PositionType): boolean;
     /**
      * Get current focused position. Return null if editor doesn't have focus at this time.
      */
-    getFocusedPosition(): NodePosition;
+    getFocusedPosition(): NodePosition | null;
     /**
      * Get an HTML element from current cursor position.
      * When expectedTags is not specified, return value is the current node (if it is HTML element)
@@ -1962,7 +1967,7 @@ class Editor implements IEditor  {
      * @param event Optional, if specified, editor will try to get cached result from the event object first.
      * If it is not cached before, query from DOM and cache the result into the event object
      */
-    getElementAtCursor(selector?: string, startFrom?: Node, event?: PluginEvent): HTMLElement;
+    getElementAtCursor(selector?: string, startFrom?: Node, event?: PluginEvent): HTMLElement | null;
     /**
      * Check if this position is at beginning of the editor.
      * This will return true if all nodes between the beginning of target node and the position are empty.
@@ -2009,7 +2014,7 @@ class Editor implements IEditor  {
      * a ContentChangedEvent will be fired with change source equal to this value
      * @param canUndoByBackspace True if this action can be undone when user press Backspace key (aka Auto Complete).
      */
-    addUndoSnapshot(callback?: (start: NodePosition, end: NodePosition) => any, changeSource?: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace?: boolean, additionalData?: ContentChangedData): void;
+    addUndoSnapshot(callback?: (start: NodePosition | null, end: NodePosition | null) => any, changeSource?: ChangeSource | CompatibleChangeSource | string, canUndoByBackspace?: boolean, additionalData?: ContentChangedData): void;
     /**
      * Whether there is an available undo/redo snapshot
      */
@@ -2049,19 +2054,22 @@ class Editor implements IEditor  {
     getBodyTraverser(startNode?: Node): IContentTraverser;
     /**
      * Get a content traverser for current selection
+     * @returns A content traverser, or null if editor never got focus before
      */
-    getSelectionTraverser(range?: Range): IContentTraverser;
+    getSelectionTraverser(range?: Range): IContentTraverser | null;
     /**
      * Get a content traverser for current block element start from specified position
      * @param startFrom Start position of the traverser. Default value is ContentPosition.SelectionStart
+     * @returns A content traverser, or null if editor never got focus before
      */
-    getBlockTraverser(startFrom?: ContentPosition | CompatibleContentPosition): IContentTraverser;
+    getBlockTraverser(startFrom?: ContentPosition | CompatibleContentPosition): IContentTraverser | null;
     /**
      * Get a text traverser of current selection
      * @param event Optional, if specified, editor will try to get cached result from the event object first.
      * If it is not cached before, query from DOM and cache the result into the event object
+     * @returns A content traverser, or null if editor never got focus before
      */
-    getContentSearcherOfCursor(event?: PluginEvent): IPositionContentSearcher;
+    getContentSearcherOfCursor(event?: PluginEvent): IPositionContentSearcher | null;
     /**
      * Run a callback function asynchronously
      * @param callback The callback function to run
@@ -2075,10 +2083,10 @@ class Editor implements IEditor  {
      */
     setEditorDomAttribute(name: string, value: string): void;
     /**
-     * get DOM attribute of editor content DIV
+     * Get DOM attribute of editor content DIV, null if there is no such attribute.
      * @param name Name of the attribute
      */
-    getEditorDomAttribute(name: string): string;
+    getEditorDomAttribute(name: string): string | null;
     /**
      * Get current relative distance from top-left corner of the given element to top-left corner of editor content DIV.
      * @param element The element to calculate from. If the given element is not in editor, return value will be null
@@ -2086,7 +2094,7 @@ class Editor implements IEditor  {
      * may be different than what user is seeing from the view. When pass false, scroll position will be ignored.
      * @returns An [x, y] array which contains the left and top distances, or null if the given element is not in editor.
      */
-    getRelativeDistanceToEditor(element: HTMLElement, addScroll?: boolean): number[];
+    getRelativeDistanceToEditor(element: HTMLElement, addScroll?: boolean): number[] | null;
     /**
      * Add a Content Edit feature.
      * @param feature The feature to add
@@ -2170,6 +2178,11 @@ class Editor implements IEditor  {
      * @param scale The new scale number to set. It should be positive number and no greater than 10, otherwise it will be ignored.
      */
     setZoomScale(scale: number): void;
+    /**
+     * @returns the current EditorCore object
+     * @throws a standard Error if there's no core object
+     */
+    private getCore;
 }
 
     /**
@@ -2579,7 +2592,13 @@ function blockFormat(editor: IEditor, callback: (region: Region, start: NodePosi
  * @param editor The Editor object
  * @param chains List chains to commit
  */
-function experimentCommitListChains(editor: IEditor, chains: VListChain[]): void;
+function commitListChains(editor: IEditor, chains: VListChain[]): void;
+
+    /**
+ * @deprecated
+ * Same with commitListChains, keep this export just for backward compatibility
+ */
+const experimentCommitListChains: typeof commitListChains;
 
     /**
  * Get dark mode color for a given color
@@ -3471,7 +3490,7 @@ const enum ExperimentalFeatures {
      */
     ImageRotate = "ImageRotate",
     /**
-     * Crop an inline image (requires ImageEdit plugin)
+     * @deprecated This feature is always enabled
      */
     ImageCrop = "ImageCrop",
     /**
@@ -4193,7 +4212,7 @@ const enum BulletListType {
      */
     ShortArrow = 4,
     /**
-     * Bullet triggered by -> or -->
+     * Bullet triggered by ->
      */
     LongArrow = 5,
     /**
@@ -4204,10 +4223,14 @@ const enum BulletListType {
      * Bullet triggered by —
      */
     Hyphen = 7,
+    /**
+     * Bullet triggered by -->
+     */
+    DoubleLongArrow = 8,
     /**
      * Maximum value of the enum
      */
-    Max = 7
+    Max = 8
 }
 
     /**
@@ -5912,7 +5935,7 @@ interface IEditor {
      * @param node The node to create InlineElement
      * @returns The BlockElement result
      */
-    getBlockElementAtNode(node: Node): BlockElement;
+    getBlockElementAtNode(node: Node): BlockElement | null;
     /**
      * Check if the node falls in the editor content
      * @param node The node to check
@@ -5998,7 +6021,7 @@ interface IEditor {
     /**
      * Delete selected content
      */
-    deleteSelectedContent(): NodePosition;
+    deleteSelectedContent(): NodePosition | null;
     /**
      * Paste into editor using a clipboardData object
      * @param clipboardData Clipboard data retrieved from clipboard
@@ -6014,7 +6037,7 @@ interface IEditor {
      * Default value is true
      * @returns current selection range, or null if editor never got focus before
      */
-    getSelectionRange(tryGetFromCache?: boolean): Range;
+    getSelectionRange(tryGetFromCache?: boolean): Range | null;
     /**
      * Get current selection range from Editor.
      * It does a live pull on the selection.
@@ -6026,7 +6049,7 @@ interface IEditor {
      * It does a live pull on the selection, if nothing retrieved, return whatever we have in cache.
      * @returns current selection path, or null if editor never got focus before
      */
-    getSelectionPath(): SelectionPath;
+    getSelectionPath(): SelectionPath | null;
     /**
      * Check if focus is in editor now
      * @returns true if focus is in editor, otherwise false
@@ -6092,7 +6115,7 @@ interface IEditor {
     /**
      * Get current focused position. Return null if editor doesn't have focus at this time.
      */
-    getFocusedPosition(): NodePosition;
+    getFocusedPosition(): NodePosition | null;
     /**
      * Get an HTML element from current cursor position.
      * When expectedTags is not specified, return value is the current node (if it is HTML element)
@@ -6105,7 +6128,7 @@ interface IEditor {
      * @param event Optional, if specified, editor will try to get cached result from the event object first.
      * If it is not cached before, query from DOM and cache the result into the event object
      */
-    getElementAtCursor(selector?: string, startFrom?: Node, event?: PluginEvent): HTMLElement;
+    getElementAtCursor(selector?: string, startFrom?: Node, event?: PluginEvent): HTMLElement | null;
     /**
      * Check if this position is at beginning of the editor.
      * This will return true if all nodes between the beginning of target node and the position are empty.
@@ -6207,19 +6230,22 @@ interface IEditor {
     getBodyTraverser(startNode?: Node): IContentTraverser;
     /**
      * Get a content traverser for current selection
+     * @returns A content traverser, or null if editor never got focus before and no range is provided
      */
-    getSelectionTraverser(range?: Range): IContentTraverser;
+    getSelectionTraverser(range?: Range): IContentTraverser | null;
     /**
      * Get a content traverser for current block element start from specified position
      * @param startFrom Start position of the traverser. Default value is ContentPosition.SelectionStart
+     * @returns A content traverser, or null if editor never got focus before
      */
-    getBlockTraverser(startFrom?: ContentPosition | CompatibleContentPosition): IContentTraverser;
+    getBlockTraverser(startFrom?: ContentPosition | CompatibleContentPosition): IContentTraverser | null;
     /**
      * Get a text traverser of current selection
      * @param event Optional, if specified, editor will try to get cached result from the event object first.
      * If it is not cached before, query from DOM and cache the result into the event object
+     * @returns A content traverser, or null if editor never got focus before
      */
-    getContentSearcherOfCursor(event?: PluginEvent): IPositionContentSearcher;
+    getContentSearcherOfCursor(event?: PluginEvent): IPositionContentSearcher | null;
     /**
      * Run a callback function asynchronously
      * @param callback The callback function to run
@@ -6233,10 +6259,10 @@ interface IEditor {
      */
     setEditorDomAttribute(name: string, value: string): void;
     /**
-     * Get DOM attribute of editor content DIV
+     * Get DOM attribute of editor content DIV, null if there is no such attribute.
      * @param name Name of the attribute
      */
-    getEditorDomAttribute(name: string): string;
+    getEditorDomAttribute(name: string): string | null;
     /**
      * Get current relative distance from top-left corner of the given element to top-left corner of editor content DIV.
      * @param element The element to calculate from. If the given element is not in editor, return value will be null
@@ -6244,7 +6270,7 @@ interface IEditor {
      * may be different than what user is seeing from the view. When pass false, scroll position will be ignored.
      * @returns An [x, y] array which contains the left and top distances, or null if the given element is not in editor.
      */
-    getRelativeDistanceToEditor(element: HTMLElement, addScroll?: boolean): number[];
+    getRelativeDistanceToEditor(element: HTMLElement, addScroll?: boolean): number[] | null;
     /**
      * Add a Content Edit feature.
      * @param feature The feature to add
@@ -6718,7 +6744,7 @@ interface CoreApiMap {
  * @param applyCurrentStyle True if apply format of current selection to the pasted content,
  * false to keep original format
  */
-type CreatePasteFragment = (core: EditorCore, clipboardData: ClipboardData, position: NodePosition, pasteAsText: boolean, applyCurrentStyle: boolean) => DocumentFragment | null;
+type CreatePasteFragment = (core: EditorCore, clipboardData: ClipboardData, position: NodePosition | null, pasteAsText: boolean, applyCurrentStyle: boolean) => DocumentFragment | null;
 
     /**
  * Ensure user will type into a container element rather than into the editor content DIV directly
@@ -6762,7 +6788,7 @@ type GetSelectionRangeEx = (core: EditorCore) => SelectionRangeEx;
  * @param core The EditorCore objects
  * @param node The node to get style from
  */
-type GetStyleBasedFormatState = (core: EditorCore, node: Node) => StyleBasedFormatState;
+type GetStyleBasedFormatState = (core: EditorCore, node: Node | null) => StyleBasedFormatState;
 
     /**
  * Get the pendable format such as underline and bold
@@ -6784,7 +6810,7 @@ type HasFocus = (core: EditorCore) => boolean;
  * @param core The EditorCore object. No op if null.
  * @param option An insert option object to specify how to insert the node
  */
-type InsertNode = (core: EditorCore, node: Node, option: InsertOption) => boolean;
+type InsertNode = (core: EditorCore, node: Node, option: InsertOption | null) => boolean;
 
     /**
  * Restore an undo snapshot into editor
@@ -6829,7 +6855,7 @@ type SwitchShadowEdit = (core: EditorCore, isOn: boolean) => void;
  * @param forceTransform By default this function will only work when editor core is in dark mode.
  * Pass true to this value to force do color transformation even editor core is in light mode
  */
-type TransformColor = (core: EditorCore, rootNode: Node, includeSelf: boolean, callback: (() => void) | null, direction: ColorTransformDirection | CompatibleColorTransformDirection, forceTransform?: boolean) => void;
+type TransformColor = (core: EditorCore, rootNode: Node | null, includeSelf: boolean, callback: (() => void) | null, direction: ColorTransformDirection | CompatibleColorTransformDirection, forceTransform?: boolean) => void;
 
     /**
  * Trigger a plugin event
@@ -6847,7 +6873,7 @@ type TriggerEvent = (core: EditorCore, pluginEvent: PluginEvent, broadcast: bool
  * selecting, will unselect the table.
  * @returns true if successful
  */
-type SelectTable = (core: EditorCore, table: HTMLTableElement, coordinates?: TableSelection) => TableSelectionRange | null;
+type SelectTable = (core: EditorCore, table: HTMLTableElement | null, coordinates?: TableSelection) => TableSelectionRange | null;
 
     /**
  * The options to specify parameters customizing an editor, used by ctor of Editor class
@@ -7751,7 +7777,7 @@ enum CompatibleExperimentalFeatures {
      */
     ImageRotate = "ImageRotate",
     /**
-     * Crop an inline image (requires ImageEdit plugin)
+     * @deprecated This feature is always enabled
      */
     ImageCrop = "ImageCrop",
     /**
@@ -8286,7 +8312,7 @@ enum CompatibleBulletListType {
      */
     ShortArrow = 4,
     /**
-     * Bullet triggered by -> or -->
+     * Bullet triggered by ->
      */
     LongArrow = 5,
     /**
@@ -8297,10 +8323,14 @@ enum CompatibleBulletListType {
      * Bullet triggered by —
      */
     Hyphen = 7,
+    /**
+     * Bullet triggered by -->
+     */
+    DoubleLongArrow = 8,
     /**
      * Maximum value of the enum
      */
-    Max = 7
+    Max = 8
 }
 
     /**
@@ -9687,13 +9717,14 @@ class TableResize implements EditorPlugin  {
 class Watermark implements EditorPlugin  {
     private watermark;
     private format?;
+    private customClass?;
     private editor;
     private disposer;
     /**
      * Create an instance of Watermark plugin
      * @param watermark The watermark string
      */
-    constructor(watermark: string, format?: DefaultFormat);
+    constructor(watermark: string, format?: DefaultFormat, customClass?: string);
     /**
      * Get a friendly name of  this plugin
      */
@@ -9755,12 +9786,6 @@ class TableCellSelection implements EditorPlugin  {
      * The table selection gets removed.
      */
     private handleScrollEvent;
-    /**
-     * Handles the Before Copy Event.
-     * Clear the selection range from the cloned Root.
-     * @param event plugin event
-     */
-    private handleBeforeCutCopy;
     /**
      * Handles the on key event.
      * @param event the plugin event
@@ -9779,10 +9804,6 @@ class TableCellSelection implements EditorPlugin  {
      */
     selectionInsideTableMouseMove(event: MouseEvent): void;
     private removeMouseUpEventListener;
-    /**
-     * When press Backspace, delete the contents inside of the selection, if it is Table Selection
-     */
-    DeleteTableContents: BuildInEditFeature<PluginKeyboardEvent>;
     private clearState;
     private getNextTD;
     private prepareSelection;