roosterjs 8.30.2 → 8.31.0

package/dist/rooster-amd.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
 
@@ -735,15 +735,12 @@ export 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
@@ -751,12 +748,18 @@ export 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
@@ -774,6 +777,8 @@ export 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
@@ -1612,7 +1617,7 @@ export 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
  */
-export function cacheGetEventData<T>(event: PluginEvent, key: string, getter: () => T): T;
+export function cacheGetEventData<T>(event: PluginEvent | null, key: string, getter: () => T): T;
 
 /**
  * Clear a cached object by its key from an event object
@@ -1671,7 +1676,7 @@ export function adjustInsertPosition(root: HTMLElement, nodeToInsert: Node, posi
  * @param core The EditorCore object.
  * @param range The range to delete
  */
-export function deleteSelectedContent(root: HTMLElement, range: Range): null;
+export function deleteSelectedContent(root: HTMLElement, range: Range): NodePosition | null;
 
 /**
  * get block element's text content.
@@ -1858,7 +1863,7 @@ export 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[];
     /**
@@ -1904,7 +1909,7 @@ export 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
@@ -1920,7 +1925,7 @@ export 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.
@@ -1934,7 +1939,7 @@ export 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
@@ -1944,11 +1949,11 @@ export 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)
@@ -1961,7 +1966,7 @@ export 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.
@@ -2008,7 +2013,7 @@ export 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
      */
@@ -2048,19 +2053,22 @@ export 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
@@ -2074,10 +2082,10 @@ export 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
@@ -2085,7 +2093,7 @@ export 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
@@ -2169,6 +2177,11 @@ export 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;
 }
 
 /**
@@ -2578,7 +2591,13 @@ export function blockFormat(editor: IEditor, callback: (region: Region, start: N
  * @param editor The Editor object
  * @param chains List chains to commit
  */
-export function experimentCommitListChains(editor: IEditor, chains: VListChain[]): void;
+export function commitListChains(editor: IEditor, chains: VListChain[]): void;
+
+/**
+ * @deprecated
+ * Same with commitListChains, keep this export just for backward compatibility
+ */
+export const experimentCommitListChains: typeof commitListChains;
 
 /**
  * Get dark mode color for a given color
@@ -3470,7 +3489,7 @@ export const enum ExperimentalFeatures {
      */
     ImageRotate = "ImageRotate",
     /**
-     * Crop an inline image (requires ImageEdit plugin)
+     * @deprecated This feature is always enabled
      */
     ImageCrop = "ImageCrop",
     /**
@@ -4192,7 +4211,7 @@ export const enum BulletListType {
      */
     ShortArrow = 4,
     /**
-     * Bullet triggered by -> or -->
+     * Bullet triggered by ->
      */
     LongArrow = 5,
     /**
@@ -4203,10 +4222,14 @@ export const enum BulletListType {
      * Bullet triggered by —
      */
     Hyphen = 7,
+    /**
+     * Bullet triggered by -->
+     */
+    DoubleLongArrow = 8,
     /**
      * Maximum value of the enum
      */
-    Max = 7
+    Max = 8
 }
 
 /**
@@ -5911,7 +5934,7 @@ export 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
@@ -5997,7 +6020,7 @@ export interface IEditor {
     /**
      * Delete selected content
      */
-    deleteSelectedContent(): NodePosition;
+    deleteSelectedContent(): NodePosition | null;
     /**
      * Paste into editor using a clipboardData object
      * @param clipboardData Clipboard data retrieved from clipboard
@@ -6013,7 +6036,7 @@ export 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.
@@ -6025,7 +6048,7 @@ export 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
@@ -6091,7 +6114,7 @@ export 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)
@@ -6104,7 +6127,7 @@ export 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.
@@ -6206,19 +6229,22 @@ export 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
@@ -6232,10 +6258,10 @@ export 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
@@ -6243,7 +6269,7 @@ export 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
@@ -6717,7 +6743,7 @@ export interface CoreApiMap {
  * @param applyCurrentStyle True if apply format of current selection to the pasted content,
  * false to keep original format
  */
-export type CreatePasteFragment = (core: EditorCore, clipboardData: ClipboardData, position: NodePosition, pasteAsText: boolean, applyCurrentStyle: boolean) => DocumentFragment | null;
+export 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
@@ -6761,7 +6787,7 @@ export type GetSelectionRangeEx = (core: EditorCore) => SelectionRangeEx;
  * @param core The EditorCore objects
  * @param node The node to get style from
  */
-export type GetStyleBasedFormatState = (core: EditorCore, node: Node) => StyleBasedFormatState;
+export type GetStyleBasedFormatState = (core: EditorCore, node: Node | null) => StyleBasedFormatState;
 
 /**
  * Get the pendable format such as underline and bold
@@ -6783,7 +6809,7 @@ export 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
  */
-export type InsertNode = (core: EditorCore, node: Node, option: InsertOption) => boolean;
+export type InsertNode = (core: EditorCore, node: Node, option: InsertOption | null) => boolean;
 
 /**
  * Restore an undo snapshot into editor
@@ -6828,7 +6854,7 @@ export 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
  */
-export type TransformColor = (core: EditorCore, rootNode: Node, includeSelf: boolean, callback: (() => void) | null, direction: ColorTransformDirection | CompatibleColorTransformDirection, forceTransform?: boolean) => void;
+export type TransformColor = (core: EditorCore, rootNode: Node | null, includeSelf: boolean, callback: (() => void) | null, direction: ColorTransformDirection | CompatibleColorTransformDirection, forceTransform?: boolean) => void;
 
 /**
  * Trigger a plugin event
@@ -6846,7 +6872,7 @@ export type TriggerEvent = (core: EditorCore, pluginEvent: PluginEvent, broadcas
  * selecting, will unselect the table.
  * @returns true if successful
  */
-export type SelectTable = (core: EditorCore, table: HTMLTableElement, coordinates?: TableSelection) => TableSelectionRange | null;
+export 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
@@ -7750,7 +7776,7 @@ export enum CompatibleExperimentalFeatures {
      */
     ImageRotate = "ImageRotate",
     /**
-     * Crop an inline image (requires ImageEdit plugin)
+     * @deprecated This feature is always enabled
      */
     ImageCrop = "ImageCrop",
     /**
@@ -8285,7 +8311,7 @@ export enum CompatibleBulletListType {
      */
     ShortArrow = 4,
     /**
-     * Bullet triggered by -> or -->
+     * Bullet triggered by ->
      */
     LongArrow = 5,
     /**
@@ -8296,10 +8322,14 @@ export enum CompatibleBulletListType {
      * Bullet triggered by —
      */
     Hyphen = 7,
+    /**
+     * Bullet triggered by -->
+     */
+    DoubleLongArrow = 8,
     /**
      * Maximum value of the enum
      */
-    Max = 7
+    Max = 8
 }
 
 /**
@@ -9686,13 +9716,14 @@ export class TableResize implements EditorPlugin  {
 export 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
      */
@@ -9754,12 +9785,6 @@ export 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
@@ -9778,10 +9803,6 @@ export 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;