roosterjs 8.31.0 → 8.32.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.31.0)
+// Type definitions for roosterjs (Version 8.32.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -716,6 +716,33 @@ const KnownCreateElementData: Record<KnownCreateElementDataIndex, CreateElementD
  */
 function moveChildNodes(target: Node, source?: Node, keepExistingChildren?: boolean): void;
 
+    /**
+ * Get the intersected Rect of elements provided
+ *
+ * @example
+ * The result of the following Elements Rects would be:
+    {
+        top: Element2.top,
+        bottom: Element1.bottom,
+        left: Element2.left,
+        right: Element2.right
+    }
+    +-------------------------+
+    | Element 1               |
+    |   +-----------------+   |
+    |   | Element2        |   |
+    |   |                 |   |
+    |   |                 |   |
+    +-------------------------+
+        |                 |
+        +-----------------+
+
+ * @param elements Elements to use.
+ * @param additionalRects additional rects to use
+ * @returns If the Rect is valid return the rect, if not, return null.
+ */
+function getIntersectedRect(elements: HTMLElement[], additionalRects?: Rect[]): Rect | null;
+
     /**
  * A virtual table class, represent an HTML table, by expand all merged cells to each separated cells
  */
@@ -912,8 +939,10 @@ class VList {
     /**
      * Write the result back into DOM tree
      * After that, this VList becomes unavailable because we set this.rootList to null
+     *
+     * @param shouldReuseAllAncestorListElements Optional - defaults to false.
      */
-    writeBack(): void;
+    writeBack(shouldReuseAllAncestorListElements?: boolean): void;
     /**
      * Sets the New List Start Property, that is going to be used to create a new List in the WriteBack function
      * @param separator The HTML element that indicates when to split the VList
@@ -1109,8 +1138,10 @@ class VListItem {
      * Write the change result back into DOM
      * @param listStack current stack of list elements
      * @param originalRoot Original list root element. It will be reused when write back if possible
+     * @param shouldReuseAllAncestorListElements Optional - defaults to false. If true, only make
+     *              sure the direct parent of this list matches the list types when writing back.
      */
-    writeBack(listStack: Node[], originalRoot?: HTMLOListElement | HTMLUListElement): void;
+    writeBack(listStack: Node[], originalRoot?: HTMLOListElement | HTMLUListElement, shouldReuseAllAncestorListElements?: boolean): void;
     /**
      * Get the index of how deep is the current node parent list inside of the original root list.
      * @example In the following structure this function would return 2
@@ -1172,7 +1203,7 @@ class VListChain {
      * After change the lists, commit the change to all lists in this chain to update the list number,
      * and clear the temporary dataset values added to list node
      */
-    commit(): void;
+    commit(shouldReuseAllAncestorListElements?: boolean): void;
     /**
      * Construct a new instance of VListChain class
      * @param editor Editor object
@@ -1208,6 +1239,13 @@ function setListItemStyle(element: HTMLLIElement, styles: string[]): void;
  */
 function getTableFormatInfo(table: HTMLTableElement): Required<TableFormat> | null;
 
+    /**
+ * Add metadata to a cell
+ * @param cell The table cell to add the metadata
+ * @param format The format of the table
+ */
+function saveTableCellMetadata(cell: HTMLTableCellElement, format: TableCellMetadataFormat): void;
+
     /**
  * Get regions impacted by the given range under the root node
  * @param root Root node to get regions from
@@ -1950,7 +1988,7 @@ class Editor implements IEditor  {
      * Focus to this editor, the selection was restored to where it was before, no unexpected scroll.
      */
     focus(): void;
-    select(arg1: Range | NodePosition | Node | SelectionPath | HTMLTableElement | null, arg2?: NodePosition | number | PositionType | TableSelection, arg3?: Node, arg4?: number | PositionType): boolean;
+    select(arg1: Range | NodePosition | Node | SelectionPath | HTMLTableElement | HTMLImageElement | 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.
      */
@@ -2088,6 +2126,8 @@ class Editor implements IEditor  {
      */
     getEditorDomAttribute(name: string): string | null;
     /**
+     * @deprecated Use getVisibleViewport() instead.
+     *
      * 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
      * @param addScroll When pass true, The return value will also add scrollLeft and scrollTop if any. So the value
@@ -2178,6 +2218,10 @@ 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;
+    /**
+     * Retrieves the rect of the visible viewport of the editor.
+     */
+    getVisibleViewport(): Rect | null;
     /**
      * @returns the current EditorCore object
      * @throws a standard Error if there's no core object
@@ -2714,6 +2758,10 @@ interface DOMEventPluginState {
      * Context menu providers, that can provide context menu items
      */
     contextMenuProviders: ContextMenuProvider<any>[];
+    /**
+     * Image selection range
+     */
+    imageSelectionRange: ImageSelectionRange | null;
 }
 
     /**
@@ -2790,6 +2838,10 @@ interface LifecyclePluginState {
      * Cached table selection path for original content
      */
     shadowEditTableSelectionPath: SelectionPath[] | null;
+    /**
+     * Cached image selection path for original content
+     */
+    shadowEditImageSelectionPath: SelectionPath[] | null;
 }
 
     /**
@@ -3537,7 +3589,18 @@ const enum ExperimentalFeatures {
      * Normalize list to make sure it can be displayed correctly in other client
      * e.g. We will move list items with "display: block" into previous list item and change tag to be DIV
      */
-    NormalizeList = "NormalizeList"
+    NormalizeList = "NormalizeList",
+    /**
+     * When a html image is selected, the selected image data will be stored by editor core.
+     */
+    ImageSelection = "ImageSelection",
+    /**
+     * With this feature enabled, when writing back a list item we will re-use all
+     * ancestor list elements, even if they don't match the types currently in the
+     * listTypes array for that item. The only list that we will ensure is correct
+     * is the one closest to the item.
+     */
+    ReuseAllAncestorListElements = "ReuseAllAncestorListElements"
 }
 
     /**
@@ -4090,7 +4153,11 @@ const enum SelectionRangeTypes {
     /**
      * Selection made inside of a single table.
      */
-    TableSelection = 1
+    TableSelection = 1,
+    /**
+     * Selection made in a image.
+     */
+    ImageSelection = 2
 }
 
     /**
@@ -4227,10 +4294,14 @@ const enum BulletListType {
      * Bullet triggered by -->
      */
     DoubleLongArrow = 8,
+    /**
+     * Bullet type circle
+     */
+    Circle = 9,
     /**
      * Maximum value of the enum
      */
-    Max = 8
+    Max = 9
 }
 
     /**
@@ -5673,6 +5744,16 @@ interface TableFormat {
     keepCellShade?: boolean;
 }
 
+    /**
+ * Format of table cell that stored as metadata
+ */
+interface TableCellMetadataFormat {
+    /**
+     * Override default background color
+     */
+    bgColorOverride?: boolean;
+}
+
     /**
  * Represents a selection made inside of a table
  */
@@ -6264,6 +6345,8 @@ interface IEditor {
      */
     getEditorDomAttribute(name: string): string | null;
     /**
+     * @deprecated Use getVisibleViewport() instead
+     *
      * 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
      * @param addScroll When pass true, The return value will also add scrollLeft and scrollTop if any. So the value
@@ -6353,6 +6436,10 @@ interface IEditor {
      * @deprecated Use getZoomScale() instead
      */
     getSizeTransformer(): SizeTransformer;
+    /**
+     * Retrieves the rect of the visible viewport of the editor.
+     */
+    getVisibleViewport(): Rect | null;
 }
 
     /**
@@ -6566,6 +6653,14 @@ interface EditorCore extends PluginState  {
      * @deprecated Use zoomScale instead
      */
     sizeTransformer: SizeTransformer;
+    /**
+     * Retrieves the Visible Viewport of the editor.
+     */
+    getVisibleViewport: () => Rect | null;
+    /**
+     * Color of the border of a selectedImage. Default color: '#DB626C'
+     */
+    imageSelectionBorderColor?: string;
 }
 
     /**
@@ -6733,6 +6828,14 @@ interface CoreApiMap {
      * @returns true if successful
      */
     selectTable: SelectTable;
+    /**
+     * Select a image and save data of the selected range
+     * @param core The EditorCore object
+     * @param image image to select
+     * @param imageId the id of the image element
+     * @returns true if successful
+     */
+    selectImage: SelectImage;
 }
 
     /**
@@ -6875,6 +6978,14 @@ type TriggerEvent = (core: EditorCore, pluginEvent: PluginEvent, broadcast: bool
  */
 type SelectTable = (core: EditorCore, table: HTMLTableElement | null, coordinates?: TableSelection) => TableSelectionRange | null;
 
+    /**
+ * Select a table and save data of the selected range
+ * @param core The EditorCore object
+ * @param image image to select
+ * @returns true if successful
+ */
+type SelectImage = (core: EditorCore, image: HTMLImageElement | null) => ImageSelectionRange | null;
+
     /**
  * The options to specify parameters customizing an editor, used by ctor of Editor class
  */
@@ -6976,6 +7087,14 @@ interface EditorOptions {
      * @deprecated Use zoomScale instead
      */
     sizeTransformer?: SizeTransformer;
+    /**
+     * Retrieves the visible viewport of the Editor. The default viewport is the Rect of the scrollContainer.
+     */
+    getVisibleViewport?: () => Rect | null;
+    /**
+     * Color of the border of a selectedImage. Default color: '#DB626C'
+     */
+    imageSelectionBorderColor?: string;
 }
 
     /**
@@ -7530,10 +7649,20 @@ interface TableSelectionRange extends SelectionRangeExBase<SelectionRangeTypes.T
     coordinates: TableSelection | undefined;
 }
 
+    /**
+ * Represents a selected image.
+ */
+interface ImageSelectionRange extends SelectionRangeExBase<SelectionRangeTypes.ImageSelection | CompatibleSelectionRangeTypes.ImageSelection> {
+    /**
+     * Selected Image
+     */
+    image: HTMLImageElement;
+}
+
     /**
  * Types of ranges used in editor api getSelectionRangeEx
  */
-type SelectionRangeEx = NormalSelectionRange | TableSelectionRange;
+type SelectionRangeEx = NormalSelectionRange | TableSelectionRange | ImageSelectionRange;
 
     /**
  * Attribute callback, will be called when HtmlSanitizer process an attribute with given name
@@ -7824,7 +7953,18 @@ enum CompatibleExperimentalFeatures {
      * Normalize list to make sure it can be displayed correctly in other client
      * e.g. We will move list items with "display: block" into previous list item and change tag to be DIV
      */
-    NormalizeList = "NormalizeList"
+    NormalizeList = "NormalizeList",
+    /**
+     * When a html image is selected, the selected image data will be stored by editor core.
+     */
+    ImageSelection = "ImageSelection",
+    /**
+     * With this feature enabled, when writing back a list item we will re-use all
+     * ancestor list elements, even if they don't match the types currently in the
+     * listTypes array for that item. The only list that we will ensure is correct
+     * is the one closest to the item.
+     */
+    ReuseAllAncestorListElements = "ReuseAllAncestorListElements"
 }
 
     /**
@@ -8236,7 +8376,11 @@ enum CompatibleSelectionRangeTypes {
     /**
      * Selection made inside of a single table.
      */
-    TableSelection = 1
+    TableSelection = 1,
+    /**
+     * Selection made in a image.
+     */
+    ImageSelection = 2
 }
 
     /**
@@ -8327,10 +8471,14 @@ enum CompatibleBulletListType {
      * Bullet triggered by -->
      */
     DoubleLongArrow = 8,
+    /**
+     * Bullet type circle
+     */
+    Circle = 9,
     /**
      * Maximum value of the enum
      */
-    Max = 8
+    Max = 9
 }
 
     /**
@@ -9839,4 +9987,27 @@ class AutoFormat implements EditorPlugin  {
     onPluginEvent(event: PluginEvent): void;
 }
 
+    /**
+ * Detect image selection and help highlight the image
+ */
+class ImageSelection implements EditorPlugin  {
+    private editor;
+    private imageId;
+    constructor();
+    /**
+     * Get a friendly name of  this plugin
+     */
+    getName(): string;
+    /**
+     * Initialize this plugin. This should only be called from Editor
+     * @param editor Editor instance
+     */
+    initialize(editor: IEditor): void;
+    /**
+     * Dispose this plugin
+     */
+    dispose(): void;
+    onPluginEvent(event: PluginEvent): void;
+}
+
 }