roosterjs 8.47.0 → 8.49.0

package/dist/rooster-amd.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.47.0)
+// Type definitions for roosterjs (Version 8.49.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -414,6 +414,45 @@ export function extractClipboardItemsForIE(dataTransfer: DataTransfer, callback:
  */
 export function createFragmentFromClipboardData(core: EditorCore, clipboardData: ClipboardData, position: NodePosition | null, pasteAsText: boolean, applyCurrentStyle: boolean, pasteAsImage: boolean, event: BeforePasteEvent): DocumentFragment;
 
+/**
+ * Handles the content when using the Image Paste Option
+ * @param imageDataUri the image uri to use for the image
+ * @param fragment fragment that will contain the content to paste.
+ */
+export function handleImagePaste(imageDataUri: string, fragment: DocumentFragment): void;
+
+/**
+ * handle the content when using the text only option
+ * @param text Text from clipboard
+ * @param position current position of the clipboard
+ * @param fragment fragment that contains the paste content.
+ */
+export function handleTextPaste(text: string, position: NodePosition | null, fragment: DocumentFragment): void;
+
+/**
+ * Retrieves the metadata from the content inside of the clipboard
+ * @param doc Document parsed from the clipboard
+ * @param event Before Paste event
+ * @param trustedHTMLHandler the trusted html handler to sanitize the content.
+ */
+export function retrieveMetadataFromClipboard(doc: Document | undefined, event: BeforePasteEvent, trustedHTMLHandler: TrustedHTMLHandler): void;
+
+/**
+ * Sanitize the content from the pasted content
+ * @param event The before paste event
+ * @param position the position of the cursor
+ */
+export function sanitizePasteContent(event: BeforePasteEvent, position: NodePosition | null): void;
+
+/**
+ * Get the paste type that will be used corresponding to the configuration
+ * @param pasteAsText Whether to paste as Text
+ * @param applyCurrentStyle Whether to apply the current format to the content
+ * @param pasteAsImage Whether to only paste the image
+ * @returns
+ */
+export function getPasteType(pasteAsText: boolean, applyCurrentStyle: boolean, pasteAsImage: boolean): PasteType;
+
 /**
  * Browser object contains browser and operating system information of current environment
  */
@@ -1315,8 +1354,9 @@ export function getRegionsFromRange(root: HTMLElement, range: Range, type: Regio
  * @param regionBase The region to get block elements from
  * @param createBlockIfEmpty When set to true, a new empty block element will be created if there is not
  * any blocks in the region. Default value is false
+ * @param deprecated Deprecated parameter, not used
  */
-export function getSelectedBlockElementsInRegion(regionBase: RegionBase, createBlockIfEmpty?: boolean, shouldApplyFormatToSpan?: boolean): BlockElement[];
+export function getSelectedBlockElementsInRegion(regionBase: RegionBase, createBlockIfEmpty?: boolean, deprecated?: boolean): BlockElement[];
 
 /**
  * Collapse nodes within this region to their common ancestor node under this region
@@ -1507,6 +1547,13 @@ export function setHtmlWithSelectionPath(rootNode: HTMLElement, html: string, tr
  */
 export function setHtmlWithMetadata(rootNode: HTMLElement, html: string, trustedHTMLHandler?: TrustedHTMLHandler): ContentMetadata | undefined;
 
+/**
+ * Extract content metadata from DOM tree
+ * @param rootNode Root of the DOM tree
+ * @returns If there is a valid content metadata node in the give DOM tree, return this metadata object, otherwise undefined
+ */
+export function extractContentMetadata(rootNode: HTMLElement): ContentMetadata | undefined;
+
 /**
  * Add the given range into selection of the given document
  * @param range The range to select
@@ -1705,6 +1752,7 @@ export function getEntityFromElement(element: HTMLElement): Entity | null;
 export function getEntitySelector(type?: string, id?: string): string;
 
 /**
+ * @deprecated
  * Create a placeholder comment node for entity
  * @param entity The entity to create placeholder from
  * @returns A placeholder comment node as
@@ -1731,7 +1779,7 @@ export function moveContentWithEntityPlaceholders(root: HTMLDivElement, entities
  * @param entities A map from entity id to entity wrapper, used for reusing existing DOM structure for entity
  * @param insertClonedNode When pass true, merge with a cloned copy of the nodes from source fragment rather than the nodes themselves @default false
  */
-export function restoreContentWithEntityPlaceholder(source: DocumentFragment, target: HTMLElement, entities: Record<string, HTMLElement> | null, insertClonedNode?: boolean): void;
+export function restoreContentWithEntityPlaceholder(source: ParentNode, target: HTMLElement, entities: Record<string, HTMLElement | KnownEntityItem> | null, insertClonedNode?: boolean): void;
 
 /**
  * Gets the cached event data by cache key from event object if there is already one.
@@ -2934,15 +2982,18 @@ export interface EntityPluginState {
         pageY: number;
     };
     /**
+     * @deprecated
      * All known entity elements
      */
-    knownEntityElements: HTMLElement[];
+    knownEntityElements?: HTMLElement[];
+    /**
+     * @deprecated
+     */
+    shadowEntityCache?: Record<string, HTMLElement>;
     /**
-     * Cache for the hydrated content of shadow DOM entity.
-     * When set content to replace the whole editor, we will cache the hydrated content
-     * before it is gone, then after that we can use the cached content to rehydrate entity
+     * Entities cached for undo snapshot
      */
-    shadowEntityCache: Record<string, HTMLElement>;
+    entityMap: Record<string, KnownEntityItem>;
 }
 
 /**
@@ -3667,15 +3718,18 @@ export const enum EntityOperation {
      */
     ReplaceTemporaryContent = 8,
     /**
-     * Notify plugins that editor has attached shadow root for an entity.
-     * Plugins can handle this event to do extra operations to the shadow root
+     * @deprecated
      */
     AddShadowRoot = 9,
     /**
-     * Notify plugins that editor has removed the shadow root of an entity
-     * Plugins can handle this event to do any necessary clean up for shadow root
+     * @deprecated
+     */
+    RemoveShadowRoot = 10,
+    /**
+     * Notify plugins that a new entity state need to be updated to an entity.
+     * This is normally happened when user undo/redo the content with an entity snapshot added by a plugin that handles entity
      */
-    RemoveShadowRoot = 10
+    UpdateEntityState = 11
 }
 
 /**
@@ -3773,6 +3827,14 @@ export const enum ExperimentalFeatures {
      * Align list elements elements to left, center and right using setAlignment API
      */
     ListItemAlignment = "ListItemAlignment",
+    /**
+     * @deprecated
+     */
+    DefaultFormatInSpan = "DefaultFormatInSpan",
+    /**
+     * @deprecated
+     */
+    DefaultFormatOnContainer = "DefaultFormatOnContainer",
     /**
      * Provide additional Tab Key Features. Requires Text Features Content Editable Features
      */
@@ -3788,11 +3850,6 @@ export const enum ExperimentalFeatures {
      * is the one closest to the item.
      */
     ReuseAllAncestorListElements = "ReuseAllAncestorListElements",
-    /**
-     * When apply default format when initialize or user type, apply the format on a SPAN element rather than
-     * the block element (In most case, the DIV element) so keep the block element clean.
-     */
-    DefaultFormatInSpan = "DefaultFormatInSpan",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
@@ -3801,10 +3858,6 @@ export const enum ExperimentalFeatures {
      * 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
      */
@@ -4185,7 +4238,7 @@ export const enum KnownCreateElementDataIndex {
      */
     TableSelector = 11,
     /**
-     * An empty line without format with span inside of it.
+     * @deprecated
      */
     EmptyLineFormatInSpan = 12
 }
@@ -4836,15 +4889,18 @@ export interface EntityOperationEventData {
      */
     rawEvent?: Event;
     /**
-     * A document fragment for entity based on Shadow DOM. This property is only available for NewEntity operation.
-     * Putting DOM nodes under this fragment will cause a shadow root to be attached to the entity wrapper
-     * with these DOM nodes under it.
-     *
-     * If there is already cached DOM nodes, they will also be put under this fragment.
-     * Plugin need to decide:
-     * 1. Apply the cache: do nothing and the DOM nodes will be appended as shadow DOM entity content
-     * 2. Discard the cache and use new content instead: clear the fragment and append new DOM nodes, then new DOM nodes will be used
-     * 3. Dehydrate this entity: clear the fragment, and leave it empty
+     * For EntityOperation.UpdateEntityState, we use this object to pass the new entity state to plugin.
+     * For other operation types, it is not used.
+     */
+    state?: string;
+    /**
+     * For EntityOperation.NewEntity, plugin can set this property to true then the entity will be persisted.
+     * A persisted entity won't be touched during undo/redo, unless it does not exist after undo/redo.
+     * For other operation types, this value will be ignored.
+     */
+    shouldPersist?: boolean;
+    /**
+     * @deprecated
      */
     contentForShadowEntity?: DocumentFragment;
 }
@@ -5349,6 +5405,12 @@ export interface ContentChangedData {
      * Optional property to store the format api name when using ChangeSource.Format
      */
     formatApiName?: string;
+    /**
+     * @optional Get entity states related to the snapshot. If it returns entity states, each state will cause
+     * an EntityOperation event with operation = EntityOperation.UpdateEntityState when undo/redo to this snapshot
+     * @returns Related entity state array
+     */
+    getEntityState?: () => EntityState[];
 }
 
 /**
@@ -6058,6 +6120,31 @@ export interface Snapshot {
      * Known colors for dark mode
      */
     knownColors: Readonly<ModeIndependentColor>[];
+    /**
+     * Entity states related to this undo snapshots. When undo/redo to this snapshot, each entity state will trigger
+     * an EntityOperation event with operation = EntityOperation.UpdateEntityState
+     */
+    entityStates?: EntityState[];
+}
+
+/**
+ * State for an entity. This is used for storing entity undo snapshot
+ */
+export interface EntityState {
+    /**
+     * Type of the entity
+     */
+    type: string;
+    /**
+     * Id of the entity
+     */
+    id: string;
+    /**
+     * The state of this entity to store into undo snapshot.
+     * The state can be any string, or a serialized JSON object.
+     * We are using string here instead of a JSON object to make sure the whole state is serializable.
+     */
+    state: string;
 }
 
 /**
@@ -6701,7 +6788,7 @@ export interface IEditor {
      * 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 | null;
+    getContentSearcherOfCursor(event?: PluginEvent | null): IPositionContentSearcher | null;
     /**
      * Run a callback function asynchronously
      * @param callback The callback function to run
@@ -7164,8 +7251,7 @@ export interface CoreApiMap {
      * @param core The EditorCore object.
      * @param position The position that user is about to type to
      * @param keyboardEvent Optional keyboard event object
-     * @param applyFormatToSpan Optional When set to true, default format (if any) will be applied to
-     * a SPAN element inside the block element instead of the block element itself.
+     * @param deprecated Deprecated parameter, not used
      */
     ensureTypeInContainer: EnsureTypeInContainer;
     /**
@@ -7313,10 +7399,9 @@ export type CreatePasteFragment = (core: EditorCore, clipboardData: ClipboardDat
  * @param core The EditorCore object.
  * @param position The position that user is about to type to
  * @param keyboardEvent Optional keyboard event object
- * @param applyFormatToSpan Optional When set to true, default format (if any) will be applied to
- * a SPAN element inside the block element instead of the block element itself.
+ * @param deprecated Deprecated parameter, not used
  */
-export type EnsureTypeInContainer = (core: EditorCore, position: NodePosition, keyboardEvent?: KeyboardEvent, applyFormatToSpan?: boolean) => void;
+export type EnsureTypeInContainer = (core: EditorCore, position: NodePosition, keyboardEvent?: KeyboardEvent, deprecated?: boolean) => void;
 
 /**
  * Focus to editor. If there is a cached selection range, use it as current selection
@@ -8186,6 +8271,24 @@ export interface ImageSelectionRange extends SelectionRangeExBase<SelectionRange
  */
 export type SelectionRangeEx = NormalSelectionRange | TableSelectionRange | ImageSelectionRange;
 
+/**
+ * Represents all info of a known entity, including its DOM element, whether it is deleted and if it can be persisted
+ */
+export interface KnownEntityItem {
+    /**
+     * The HTML element of entity wrapper
+     */
+    element: HTMLElement;
+    /**
+     * Whether this entity is deleted.
+     */
+    isDeleted?: boolean;
+    /**
+     * Whether we want to persist this entity element during undo/redo
+     */
+    canPersist?: boolean;
+}
+
 /**
  * Attribute callback, will be called when HtmlSanitizer process an attribute with given name
  * @param value Value of the attribute
@@ -8493,6 +8596,14 @@ export enum CompatibleExperimentalFeatures {
      * Align list elements elements to left, center and right using setAlignment API
      */
     ListItemAlignment = "ListItemAlignment",
+    /**
+     * @deprecated
+     */
+    DefaultFormatInSpan = "DefaultFormatInSpan",
+    /**
+     * @deprecated
+     */
+    DefaultFormatOnContainer = "DefaultFormatOnContainer",
     /**
      * Provide additional Tab Key Features. Requires Text Features Content Editable Features
      */
@@ -8508,11 +8619,6 @@ export enum CompatibleExperimentalFeatures {
      * is the one closest to the item.
      */
     ReuseAllAncestorListElements = "ReuseAllAncestorListElements",
-    /**
-     * When apply default format when initialize or user type, apply the format on a SPAN element rather than
-     * the block element (In most case, the DIV element) so keep the block element clean.
-     */
-    DefaultFormatInSpan = "DefaultFormatInSpan",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
@@ -8521,10 +8627,6 @@ export enum CompatibleExperimentalFeatures {
      * 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
      */
@@ -8782,15 +8884,18 @@ export enum CompatibleEntityOperation {
      */
     ReplaceTemporaryContent = 8,
     /**
-     * Notify plugins that editor has attached shadow root for an entity.
-     * Plugins can handle this event to do extra operations to the shadow root
+     * @deprecated
      */
     AddShadowRoot = 9,
     /**
-     * Notify plugins that editor has removed the shadow root of an entity
-     * Plugins can handle this event to do any necessary clean up for shadow root
+     * @deprecated
      */
-    RemoveShadowRoot = 10
+    RemoveShadowRoot = 10,
+    /**
+     * Notify plugins that a new entity state need to be updated to an entity.
+     * This is normally happened when user undo/redo the content with an entity snapshot added by a plugin that handles entity
+     */
+    UpdateEntityState = 11
 }
 
 /**
@@ -9654,7 +9759,7 @@ export enum CompatibleKnownCreateElementDataIndex {
      */
     TableSelector = 11,
     /**
-     * An empty line without format with span inside of it.
+     * @deprecated
      */
     EmptyLineFormatInSpan = 12
 }