roosterjs 8.31.0 → 8.32.0

package/dist/rooster-amd.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
 
@@ -715,6 +715,33 @@ export const KnownCreateElementData: Record<KnownCreateElementDataIndex, CreateE
  */
 export 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.
+ */
+export 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
  */
@@ -911,8 +938,10 @@ export 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
@@ -1108,8 +1137,10 @@ export 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
@@ -1171,7 +1202,7 @@ export 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
@@ -1207,6 +1238,13 @@ export function setListItemStyle(element: HTMLLIElement, styles: string[]): void
  */
 export 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
+ */
+export 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
@@ -1949,7 +1987,7 @@ 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: 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.
      */
@@ -2087,6 +2125,8 @@ export 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
@@ -2177,6 +2217,10 @@ 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;
+    /**
+     * 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
@@ -2713,6 +2757,10 @@ export interface DOMEventPluginState {
      * Context menu providers, that can provide context menu items
      */
     contextMenuProviders: ContextMenuProvider<any>[];
+    /**
+     * Image selection range
+     */
+    imageSelectionRange: ImageSelectionRange | null;
 }
 
 /**
@@ -2789,6 +2837,10 @@ export interface LifecyclePluginState {
      * Cached table selection path for original content
      */
     shadowEditTableSelectionPath: SelectionPath[] | null;
+    /**
+     * Cached image selection path for original content
+     */
+    shadowEditImageSelectionPath: SelectionPath[] | null;
 }
 
 /**
@@ -3536,7 +3588,18 @@ export 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"
 }
 
 /**
@@ -4089,7 +4152,11 @@ export const enum SelectionRangeTypes {
     /**
      * Selection made inside of a single table.
      */
-    TableSelection = 1
+    TableSelection = 1,
+    /**
+     * Selection made in a image.
+     */
+    ImageSelection = 2
 }
 
 /**
@@ -4226,10 +4293,14 @@ export const enum BulletListType {
      * Bullet triggered by -->
      */
     DoubleLongArrow = 8,
+    /**
+     * Bullet type circle
+     */
+    Circle = 9,
     /**
      * Maximum value of the enum
      */
-    Max = 8
+    Max = 9
 }
 
 /**
@@ -5672,6 +5743,16 @@ export interface TableFormat {
     keepCellShade?: boolean;
 }
 
+/**
+ * Format of table cell that stored as metadata
+ */
+export interface TableCellMetadataFormat {
+    /**
+     * Override default background color
+     */
+    bgColorOverride?: boolean;
+}
+
 /**
  * Represents a selection made inside of a table
  */
@@ -6263,6 +6344,8 @@ export 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
@@ -6352,6 +6435,10 @@ export interface IEditor {
      * @deprecated Use getZoomScale() instead
      */
     getSizeTransformer(): SizeTransformer;
+    /**
+     * Retrieves the rect of the visible viewport of the editor.
+     */
+    getVisibleViewport(): Rect | null;
 }
 
 /**
@@ -6565,6 +6652,14 @@ export 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;
 }
 
 /**
@@ -6732,6 +6827,14 @@ export 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;
 }
 
 /**
@@ -6874,6 +6977,14 @@ export type TriggerEvent = (core: EditorCore, pluginEvent: PluginEvent, broadcas
  */
 export 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
+ */
+export type SelectImage = (core: EditorCore, image: HTMLImageElement | null) => ImageSelectionRange | null;
+
 /**
  * The options to specify parameters customizing an editor, used by ctor of Editor class
  */
@@ -6975,6 +7086,14 @@ export 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;
 }
 
 /**
@@ -7529,10 +7648,20 @@ export interface TableSelectionRange extends SelectionRangeExBase<SelectionRange
     coordinates: TableSelection | undefined;
 }
 
+/**
+ * Represents a selected image.
+ */
+export interface ImageSelectionRange extends SelectionRangeExBase<SelectionRangeTypes.ImageSelection | CompatibleSelectionRangeTypes.ImageSelection> {
+    /**
+     * Selected Image
+     */
+    image: HTMLImageElement;
+}
+
 /**
  * Types of ranges used in editor api getSelectionRangeEx
  */
-export type SelectionRangeEx = NormalSelectionRange | TableSelectionRange;
+export type SelectionRangeEx = NormalSelectionRange | TableSelectionRange | ImageSelectionRange;
 
 /**
  * Attribute callback, will be called when HtmlSanitizer process an attribute with given name
@@ -7823,7 +7952,18 @@ export 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"
 }
 
 /**
@@ -8235,7 +8375,11 @@ export enum CompatibleSelectionRangeTypes {
     /**
      * Selection made inside of a single table.
      */
-    TableSelection = 1
+    TableSelection = 1,
+    /**
+     * Selection made in a image.
+     */
+    ImageSelection = 2
 }
 
 /**
@@ -8326,10 +8470,14 @@ export enum CompatibleBulletListType {
      * Bullet triggered by -->
      */
     DoubleLongArrow = 8,
+    /**
+     * Bullet type circle
+     */
+    Circle = 9,
     /**
      * Maximum value of the enum
      */
-    Max = 8
+    Max = 9
 }
 
 /**
@@ -9838,3 +9986,26 @@ export class AutoFormat implements EditorPlugin  {
     onPluginEvent(event: PluginEvent): void;
 }
 
+/**
+ * Detect image selection and help highlight the image
+ */
+export 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;
+}
+