roosterjs 8.46.0 → 8.48.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.46.0)
+// Type definitions for roosterjs (Version 8.48.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -724,7 +724,8 @@ function getInnerHTML(node: HTMLElement | DocumentFragment): string;
  * @param isBackgroundColor Whether set background color or text color
  * @param isDarkMode Whether current mode is dark mode. @default false
  * @param shouldAdaptTheFontColor Whether the font color needs to be adapted to be visible in a dark or bright background color. @default false
- * @param darkColorHandler An optional dark color handler object. When it is passed, we will use this handler to do variable-based dark color instead of original dataset base dark color
+ * @param darkColorHandler A dark color handler object. This is now required.
+ * We keep it optional only for backward compatibility. If it is not passed, color will not be set.
  */
 function setColor(element: HTMLElement, color: string | ModeIndependentColor, isBackgroundColor: boolean, isDarkMode?: boolean, shouldAdaptTheFontColor?: boolean, darkColorHandler?: DarkColorHandler | null): void;
 
@@ -1315,8 +1316,9 @@ function getRegionsFromRange(root: HTMLElement, range: Range, type: RegionType |
  * @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
  */
-function getSelectedBlockElementsInRegion(regionBase: RegionBase, createBlockIfEmpty?: boolean, shouldApplyFormatToSpan?: boolean): BlockElement[];
+function getSelectedBlockElementsInRegion(regionBase: RegionBase, createBlockIfEmpty?: boolean, deprecated?: boolean): BlockElement[];
 
     /**
  * Collapse nodes within this region to their common ancestor node under this region
@@ -2303,9 +2305,9 @@ class EditorBase<TEditorCore extends EditorCore, TEditorOptions extends EditorOp
      */
     transformToDarkColor(node: Node): void;
     /**
-     * Get a darkColorHandler object for this editor. It will return null if experimental feature "VariableBasedDarkColor" is not enabled
+     * Get a darkColorHandler object for this editor.
      */
-    getDarkColorHandler(): DarkColorHandler | null;
+    getDarkColorHandler(): DarkColorHandler;
     /**
      * Make the editor in "Shadow Edit" mode.
      * In Shadow Edit mode, all format change will finally be ignored.
@@ -2456,8 +2458,11 @@ function getElementBasedFormatState(editor: IEditor, event?: PluginEvent): Eleme
  * If isBlock is true, entity will be insert below this position
  * @param insertToRegionRoot @optional When pass true, insert the entity at the root level of current region.
  * Parent nodes will be split if need
+ * @param focusAfterEntity @optional When pass true, focus will be moved next to the entity. For inline entity,
+ * focus will be after right after the entity (and the delimiter if exist). For block entity, focus will be in
+ * the new empty line below the entity
  */
-function insertEntity(editor: IEditor, type: string, contentNode: Node, isBlock: boolean, isReadonly: boolean, position?: NodePosition | ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd, insertToRegionRoot?: boolean): Entity;
+function insertEntity(editor: IEditor, type: string, contentNode: Node, isBlock: boolean, isReadonly: boolean, position?: NodePosition | ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | CompatibleContentPosition.Begin | CompatibleContentPosition.End | CompatibleContentPosition.DomEnd, insertToRegionRoot?: boolean, focusAfterEntity?: boolean): Entity;
 
     /**
  * Insert an image to editor at current selection
@@ -3540,6 +3545,7 @@ const enum ContentPosition {
 }
 
     /**
+ * @deprecated
  * Constants string for dataset names used by dark mode
  */
 const enum DarkModeDatasetNames {
@@ -3758,13 +3764,29 @@ const enum ExperimentalFeatures {
      */
     ImageSelection = "ImageSelection",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     * @deprecated this feature is always enabled
+     * Use variable-based dark mode solution rather than dataset-based solution.
+     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
+     * if you need them work for dark mode
      */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
+    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
+     * @deprecated this feature is always enabled
      * 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
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
@@ -3776,25 +3798,14 @@ 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",
-    /**
-     * Use variable-based dark mode solution rather than dataset-based solution.
-     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
-     * if you need them work for dark mode
-     */
-    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
     ReusableContentModel = "ReusableContentModel",
     /**
-     * Apply default format on editor container
+     * Handle keyboard editing event with Content Model
      */
-    DefaultFormatOnContainer = "DefaultFormatOnContainer",
+    EditWithContentModel = "EditWithContentModel",
     /**
      * Delete table with Backspace key with the whole was selected with table selector
      */
@@ -4175,7 +4186,7 @@ const enum KnownCreateElementDataIndex {
      */
     TableSelector = 11,
     /**
-     * An empty line without format with span inside of it.
+     * @deprecated
      */
     EmptyLineFormatInSpan = 12
 }
@@ -4368,7 +4379,13 @@ const enum PluginEventType {
      * EXPERIMENTAL FEATURE
      * Editor changed the selection.
      */
-    SelectionChanged = 22
+    SelectionChanged = 22,
+    /**
+     * EXPERIMENTAL FEATURE
+     * Editor content is about to be changed by keyboard event.
+     * This is only used by Content Model editing
+     */
+    BeforeKeyboardEditing = 23
 }
 
     /**
@@ -4563,6 +4580,28 @@ const enum DefinitionType {
     Customize = 5
 }
 
+    /**
+ * Enum for paste options
+ */
+const enum PasteType {
+    /**
+     * Default paste behavior
+     */
+    Normal = 0,
+    /**
+     * Paste only the plain text
+     */
+    AsPlainText = 1,
+    /**
+     * Apply the current style to pasted content
+     */
+    MergeFormat = 2,
+    /**
+     * If there is a image uri in the clipboard, paste the content as image element
+     */
+    AsImage = 3
+}
+
     /**
  * Provides a chance for plugin to change the content before it is copied from editor.
  */
@@ -4661,6 +4700,10 @@ interface BeforePasteEventData {
      * Attributes of the root "HTML" tag
      */
     htmlAttributes: Record<string, string>;
+    /**
+     * Paste type option (as plain text, merge format, normal, as image)
+     */
+    readonly pasteType: PasteType | CompatiblePasteType;
 }
 
     /**
@@ -5051,7 +5094,7 @@ interface PluginContextMenuEventData {
     /**
  * Editor plugin event interface
  */
-type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent | SelectionChangedEvent | CompatibleBeforeCutCopyEvent | CompatibleBeforeDisposeEvent | CompatibleBeforePasteEvent | CompatibleBeforeSetContentEvent | CompatibleContentChangedEvent | CompatibleEditImageEvent | CompatibleEditorReadyEvent | CompatibleEntityOperationEvent | CompatibleExtractContentWithDomEvent | CompatiblePendingFormatStateChangedEvent | CompatiblePluginDomEvent | CompatibleEnterShadowEditEvent | CompatibleLeaveShadowEditEvent | CompatibleZoomChangedEvent | CompatibleSelectionChangedEvent;
+type PluginEvent = BeforeCutCopyEvent | BeforePasteEvent | ContentChangedEvent | EntityOperationEvent | ExtractContentWithDomEvent | PluginDomEvent | EditorReadyEvent | BeforeDisposeEvent | PendingFormatStateChangedEvent | EnterShadowEditEvent | LeaveShadowEditEvent | EditImageEvent | BeforeSetContentEvent | ZoomChangedEvent | SelectionChangedEvent | BeforeKeyboardEditingEvent | CompatibleBeforeCutCopyEvent | CompatibleBeforeDisposeEvent | CompatibleBeforePasteEvent | CompatibleBeforeSetContentEvent | CompatibleContentChangedEvent | CompatibleEditImageEvent | CompatibleEditorReadyEvent | CompatibleEntityOperationEvent | CompatibleExtractContentWithDomEvent | CompatiblePendingFormatStateChangedEvent | CompatiblePluginDomEvent | CompatibleEnterShadowEditEvent | CompatibleLeaveShadowEditEvent | CompatibleZoomChangedEvent | CompatibleSelectionChangedEvent | CompatibleBeforeKeyboardEditingEvent;
 
     /**
  * A type to extract data part of a plugin event type. Data part is the plugin event without eventType field.
@@ -5163,6 +5206,28 @@ interface SelectionChangedEventData {
  * Represents an event that will be fired when the user changed the selection
  */
 interface CompatibleSelectionChangedEvent extends SelectionChangedEventData, BasePluginEvent<CompatiblePluginEventType.SelectionChanged> {
+}
+
+    /**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+interface BeforeKeyboardEditingEvent extends BeforeKeyboardEditingData, BasePluginEvent<PluginEventType.BeforeKeyboardEditing> {
+}
+
+    /**
+ * Data of BeforeKeyboardEditing
+ */
+interface BeforeKeyboardEditingData {
+    /**
+     * Raw DOM event
+     */
+    rawEvent: KeyboardEvent;
+}
+
+    /**
+ * Provides a chance for plugin to change the content before it is copied from editor.
+ */
+interface CompatibleBeforeKeyboardEditingEvent extends BeforeKeyboardEditingData, BasePluginEvent<CompatiblePluginEventType.BeforeKeyboardEditing> {
 }
 
     /**
@@ -5680,7 +5745,7 @@ interface InsertOptionBase {
  * The "basic" insertNode related ContentPositions that require no additional parameters to use.
  */
 interface InsertOptionBasic extends InsertOptionBase  {
-    position: ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | ContentPosition.Outside | ContentPosition.SelectionStart;
+    position: ContentPosition.Begin | ContentPosition.End | ContentPosition.DomEnd | ContentPosition.Outside | ContentPosition.SelectionStart | CompatibleContentPosition.Begin | CompatibleContentPosition.End | CompatibleContentPosition.DomEnd | CompatibleContentPosition.Outside | CompatibleContentPosition.SelectionStart;
 }
 
     /**
@@ -6637,7 +6702,7 @@ 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
@@ -6707,9 +6772,9 @@ interface IEditor {
      */
     transformToDarkColor(node: Node): void;
     /**
-     * Get a darkColorHandler object for this editor. It will return null if experimental feature "VariableBasedDarkColor" is not enabled
+     * Get a darkColorHandler object for this editor.
      */
-    getDarkColorHandler(): DarkColorHandler | null;
+    getDarkColorHandler(): DarkColorHandler;
     /**
      * Make the editor in "Shadow Edit" mode.
      * In Shadow Edit mode, all format change will finally be ignored.
@@ -7042,7 +7107,7 @@ interface EditorCore extends PluginState  {
      * Dark model handler for the editor, used for variable-based solution.
      * If keep it null, editor will still use original dataset-based dark mode solution.
      */
-    darkColorHandler?: DarkColorHandler;
+    darkColorHandler: DarkColorHandler;
 }
 
     /**
@@ -7100,8 +7165,7 @@ 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;
     /**
@@ -7249,10 +7313,9 @@ type CreatePasteFragment = (core: EditorCore, clipboardData: ClipboardData, posi
  * @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
  */
-type EnsureTypeInContainer = (core: EditorCore, position: NodePosition, keyboardEvent?: KeyboardEvent, applyFormatToSpan?: boolean) => void;
+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
@@ -8418,13 +8481,29 @@ enum CompatibleExperimentalFeatures {
      */
     ImageSelection = "ImageSelection",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     * @deprecated this feature is always enabled
+     * Use variable-based dark mode solution rather than dataset-based solution.
+     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
+     * if you need them work for dark mode
      */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
+    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
+     * @deprecated this feature is always enabled
      * 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
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
@@ -8436,25 +8515,14 @@ 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",
-    /**
-     * Use variable-based dark mode solution rather than dataset-based solution.
-     * When enable this feature, need to pass in a DarkModelHandler object to each call of setColor and applyFormat
-     * if you need them work for dark mode
-     */
-    VariableBasedDarkColor = "VariableBasedDarkColor",
     /**
      * Reuse existing DOM structure if possible when convert Content Model back to DOM tree
      */
     ReusableContentModel = "ReusableContentModel",
     /**
-     * Apply default format on editor container
+     * Handle keyboard editing event with Content Model
      */
-    DefaultFormatOnContainer = "DefaultFormatOnContainer",
+    EditWithContentModel = "EditWithContentModel",
     /**
      * Delete table with Backspace key with the whole was selected with table selector
      */
@@ -8569,7 +8637,35 @@ enum CompatiblePluginEventType {
      * EXPERIMENTAL FEATURE
      * Editor changed the selection.
      */
-    SelectionChanged = 22
+    SelectionChanged = 22,
+    /**
+     * EXPERIMENTAL FEATURE
+     * Editor content is about to be changed by keyboard event.
+     * This is only used by Content Model editing
+     */
+    BeforeKeyboardEditing = 23
+}
+
+    /**
+ * Enum for paste options
+ */
+enum CompatiblePasteType {
+    /**
+     * Default paste behavior
+     */
+    Normal = 0,
+    /**
+     * Paste only the plain text
+     */
+    AsPlainText = 1,
+    /**
+     * Apply the current style to pasted content
+     */
+    MergeFormat = 2,
+    /**
+     * If there is a image uri in the clipboard, paste the content as image element
+     */
+    AsImage = 3
 }
 
     /**
@@ -9102,6 +9198,7 @@ enum CompatibleContentType {
 }
 
     /**
+ * @deprecated
  * Constants string for dataset names used by dark mode
  */
 enum CompatibleDarkModeDatasetNames {
@@ -9555,7 +9652,7 @@ enum CompatibleKnownCreateElementDataIndex {
      */
     TableSelector = 11,
     /**
-     * An empty line without format with span inside of it.
+     * @deprecated
      */
     EmptyLineFormatInSpan = 12
 }