roosterjs 9.26.0 → 9.29.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 9.26.0)
+// Type definitions for roosterjs (Version 9.29.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -76,7 +76,7 @@ type ShallowMutableContentModelWithDataset<T> = ShallowMutableMark & {
     /**
  * The format object for a paragraph in Content Model
  */
-type ContentModelBlockFormat = BackgroundColorFormat & DirectionFormat & TextAlignFormat & HtmlAlignFormat & MarginFormat & PaddingFormat & LineHeightFormat & WhiteSpaceFormat & BorderFormat & TextIndentFormat;
+type ContentModelBlockFormat = BackgroundColorFormat & DirectionFormat & TextAlignFormat & HtmlAlignFormat & MarginFormat & PaddingFormat & LineHeightFormat & WhiteSpaceFormat & BorderFormat & TextIndentFormat & IdFormat;
 
     /**
  * Format of table cell
@@ -236,7 +236,7 @@ interface ContentModelFormatMap {
     /**
  * The format object for an image in Content Model
  */
-type ContentModelImageFormat = ContentModelSegmentFormat & IdFormat & SizeFormat & MarginFormat & PaddingFormat & BorderFormat & BoxShadowFormat & DisplayFormat & FloatFormat & VerticalAlignFormat;
+type ContentModelImageFormat = ContentModelSegmentFormat & IdFormat & SizeFormat & MarginFormat & PaddingFormat & BorderFormat & BoxShadowFormat & DisplayFormat & FloatFormat & VerticalAlignFormat & ImageStateFormat;
 
     /**
  * The format object for an entity in Content Model
@@ -307,6 +307,10 @@ interface FormatHandlerTypeMap {
      * Format for IdFormat
      */
     id: IdFormat;
+    /**
+     * Format of ImageStateFormat
+     */
+    imageState: ImageStateFormat;
     /**
      * Format for ItalicFormat
      */
@@ -891,6 +895,16 @@ type UndeletableFormat = {
     undeletable?: boolean;
 };
 
+    /**
+ * The hidden property of an image
+ */
+type ImageStateFormat = {
+    /**
+     * A hidden marker for the image state
+     */
+    imageState?: string;
+};
+
     /**
  * Represents dataset format of Content Model
  */
@@ -3161,6 +3175,11 @@ interface DomIndexer {
      * Node1 will become "FooBar", Node2 will be removed from DOM tree
      */
     onMergeText: (targetText: Text, sourceText: Text) => void;
+    /**
+     * Clear index from the given container and all its descendants
+     * @param container The root container to clear index from
+     */
+    clearIndex: (container: Node) => void;
     /**
      * When document content or selection is changed by user, we need to use this function to update the content model
      * to reflect the latest document. This process can fail since the selected node may not have a related model data structure.
@@ -3590,9 +3609,15 @@ type ExperimentalFeature = /**
  */
  | 'LegacyImageSelection'
 /**
+ * @deprecated Please use the shouldHandleEnterKey option of the EditPlugin Options
  * Use Content Model handle ENTER key
  */
- | 'HandleEnterKey';
+ | 'HandleEnterKey'
+/**
+ *  Prevent default browser behavior for copy/cut event,
+ *  and set the clipboard data with custom implementation.
+ */
+ | 'CustomCopyCut';
 
     /**
  * Options for editor
@@ -4855,9 +4880,13 @@ interface ContentModelFormatState {
      */
     fontWeight?: string;
     /**
-     * Format of image, if there is table at cursor position
+     * Format of image, if there is image at cursor position
      */
     imageFormat?: ImageFormatState;
+    /**
+     * Editing metadata of image, if there is image at cursor position
+     */
+    imageEditingMetadata?: ImageMetadataFormat | null;
     /**
      * Letter spacing
      */
@@ -5306,7 +5335,15 @@ type TrustedHTMLHandler = DOMCreator | LegacyTrustedHTMLHandler;
  * A handler type to convert HTML string to a DOM object
  */
 interface DOMCreator {
+    /**
+     * Callback to convert HTML string to a DOM object
+     */
     htmlToDOM: (html: string) => Document;
+    /**
+     * Flag to indicate if this handler is bypassed or not.
+     * If this is true, it means that when converting HTML string to DOM object, we don't need to do any conversion.
+     */
+    isBypassed?: boolean;
 }
 
     /**
@@ -6925,7 +6962,7 @@ function isGeneralSegment(group: ReadonlyContentModelBlockGroup | ReadonlyConten
  * @param parent Parent block group of the unwrapping group
  * @param groupToUnwrap  The block group to unwrap
  */
-function unwrapBlock(parent: ReadonlyContentModelBlockGroup | null, groupToUnwrap: ReadonlyContentModelBlockGroup & ReadonlyContentModelBlock): void;
+function unwrapBlock(parent: ReadonlyContentModelBlockGroup | null, groupToUnwrap: ReadonlyContentModelBlockGroup & ReadonlyContentModelBlock, formatsToKeep?: (keyof ContentModelBlockFormat)[]): void;
 
     /**
  * Add a given segment into a paragraph from its parent group. If the last block of the given group is not paragraph, create a new paragraph.
@@ -6964,12 +7001,49 @@ function normalizeSingleSegment(paragraph: ReadonlyContentModelParagraph, segmen
  */
 function mergeTextSegments(block: ShallowMutableContentModelParagraph): void;
 
+    /**
+ * Some format values can be changed when apply to DOM, such as font family.
+ * This function will normalize the format and return the same string after DOM modification.
+ * @param format The format to be normalized
+ * @return Normalized format
+ */
+function normalizeSegmentFormat(format: ContentModelSegmentFormat, environment: EditorEnvironment): ContentModelSegmentFormat;
+
     /**
  * For a given block, if it is a paragraph, set it to be not-implicit
  * @param block The block to check
  */
 function setParagraphNotImplicit(block: ReadonlyContentModelBlock): void;
 
+    /**
+ * Copy formats from source to target with only specified keys
+ * @param targetFormat The format object to copy format to
+ * @param sourceFormat The format object to copy format from
+ * @param formatKeys The format keys to copy
+ * @param deleteOriginalFormat True to delete the original format from sourceFormat, false to keep it. @default false
+ */
+function copyFormat<T extends ContentModelFormatBase>(targetFormat: T, sourceFormat: T, formatKeys: (keyof T)[], deleteOriginalFormat?: boolean): void;
+
+    /**
+ * When copy format from one block to another, these are all the formats that we can copy
+ */
+const ListFormats: (keyof ContentModelBlockFormat)[];
+
+    /**
+ * When copy format between list and paragraph, these are the formats that we can copy and keep in the source
+ */
+const ListFormatsToKeep: (keyof ContentModelBlockFormat)[];
+
+    /**
+ * When copy format between list and paragraph, these are the formats that we can copy and remove from the source
+ */
+const ListFormatsToMove: (keyof ContentModelBlockFormat)[];
+
+    /**
+ * When copy format between paragraphs, these are the formats that we can copy
+ */
+const ParagraphFormats: (keyof ContentModelBlockFormat)[];
+
     /**
  * Get the list number for a list item according to list style type and its index number
  * @param styleType The list style number, should be a value of NumberingListType type
@@ -7188,6 +7262,14 @@ function readFile(file: File, callback: (dataUrl: string | null) => void): void;
  */
 function transformColor(rootNode: Node, includeSelf: boolean, direction: 'lightToDark' | 'darkToLight', darkColorHandler?: DarkColorHandler): void;
 
+    /**
+ * Normalize font family string to a standard format
+ * Add quotes around font family names that contain non-alphanumeric/dash characters
+ * @param fontFamily The font family string to normalize
+ * @returns The normalized font family string
+ */
+function normalizeFontFamily(fontFamily: string): string;
+
     /**
  * Extract clipboard items to be a ClipboardData object for IE
  * @param items The clipboard items retrieve from a DataTransfer object
@@ -7215,6 +7297,16 @@ function setParagraphMarker(element: HTMLElement, marker: string): void;
  */
 function getParagraphMarker(element: HTMLElement): string | undefined;
 
+    /**
+ * Set image state to element. This is used to store a image state.
+ */
+function setImageState(element: HTMLElement, marker: string): void;
+
+    /**
+ * Get image state from element. This is used to store a image state.
+ */
+function getImageState(element: HTMLElement): string | undefined;
+
     /**
  * Check if the given content model block or block group is of the expected block group type
  * @param input The object to check
@@ -7693,6 +7785,18 @@ const BulletListType: {
      * Bullet type circle
      */
     Circle: number;
+    /**
+     * Box Shadow bullet type
+     */
+    BoxShadow: number;
+    /**
+     * Rhombus with a cross inside
+     */
+    Xrhombus: number;
+    /**
+     * Check mark bullet type
+     */
+    CheckMark: number;
     /**
      * Maximum value of the enum
      */
@@ -8497,6 +8601,14 @@ function insertTableColumn(table: ShallowMutableContentModelTable, operation: Ta
  */
 function clearSelectedCells(table: ReadonlyContentModelTable, sel: TableSelectionCoordinates): void;
 
+    /**
+ * Create an EditorContext for an entity
+ * @param editor The editor object
+ * @param entity The entity to create the context for
+ * @returns The generated EditorContext for the entity
+ */
+function createEditorContextForEntity(editor: IEditor, entity: ContentModelEntity): EditorContext;
+
     /**
  * Invoke a callback to format the selected table using Content Model
  * @param editor The editor object
@@ -8632,8 +8744,9 @@ function getListAnnounceData(path: ReadonlyContentModelBlockGroup[]): AnnounceDa
  * @param type The type of block to query
  * @param filter Optional selector to filter the blocks
  * @param findFirstOnly True to return the first block only, false to return all blocks
+ * @param shouldExpandEntity Optional function to determine if an entity's children should be recursively queried, should return a EditorContext if the entity should be expanded, or null if not
  */
-function queryContentModelBlocks<T extends ReadonlyContentModelBlock>(group: ReadonlyContentModelBlockGroup, type: T extends ReadonlyContentModelBlockBase<infer U> ? U : never, filter?: (element: T) => element is T, findFirstOnly?: boolean): T[];
+function queryContentModelBlocks<T extends ReadonlyContentModelBlock>(group: ReadonlyContentModelBlockGroup, type: T extends ReadonlyContentModelBlockBase<infer U> ? U : never, filter?: (element: T) => element is T, findFirstOnly?: boolean, shouldExpandEntity?: (entity: ContentModelEntity) => EditorContext | null): T[];
 
     /**
  * TableEdit plugin, provides the ability to resize a table by drag-and-drop
@@ -8642,6 +8755,7 @@ class TableEditPlugin implements EditorPlugin  {
     private anchorContainerSelector?;
     private onTableEditorCreated?;
     private disableFeatures?;
+    private tableSelector;
     private editor;
     private onMouseMoveDisposer;
     private tableRectMap;
@@ -8653,8 +8767,9 @@ class TableEditPlugin implements EditorPlugin  {
      * If not specified, the plugin will be inserted in document.body
      * @param onTableEditorCreated An optional callback to customize the Table Editors elements when created.
      * @param disableFeatures An optional array of TableEditFeatures to disable
+     * @param tableSelector A function to select the tables to be edited. By default, it selects all contentEditable tables.
      */
-    constructor(anchorContainerSelector?: string | undefined, onTableEditorCreated?: OnTableEditorCreatedCallback | undefined, disableFeatures?: TableEditFeatureName[] | undefined);
+    constructor(anchorContainerSelector?: string | undefined, onTableEditorCreated?: OnTableEditorCreatedCallback | undefined, disableFeatures?: TableEditFeatureName[] | undefined, tableSelector?: (domHelper: DOMHelper) => TableWithRoot[]);
     /**
      * Get a friendly name of this plugin
      */
@@ -8677,10 +8792,10 @@ class TableEditPlugin implements EditorPlugin  {
     private onMouseMove;
     /**
      * @internal Public only for unit test
-     * @param table Table to use when setting the Editors
+     * @param entry Table to use when setting the Editors
      * @param event (Optional) Mouse event
      */
-    setTableEditor(table: HTMLTableElement | null, event?: MouseEvent): void;
+    setTableEditor(entry: TableWithRoot | null, event?: MouseEvent): void;
     private invalidateTableRects;
     private disposeTableEditor;
     private ensureTableRects;
@@ -8696,6 +8811,22 @@ type OnTableEditorCreatedCallback = (featureType: TableEditFeatureName, element:
  */
 type TableEditFeatureName = 'HorizontalTableInserter' | 'VerticalTableInserter' | 'TableMover' | 'TableResizer' | 'TableSelector' | 'CellResizer';
 
+    /**
+ * Represents a table and its container (logical root)
+ */
+interface TableWithRoot {
+    /**
+     * The table element
+     */
+    table: HTMLTableElement;
+    /**
+     * The logical root element of the table
+     * This is the element that contains the table and all its ancestors
+     * It is used to determine the logical root of the table
+     */
+    logicalRoot: HTMLDivElement | null;
+}
+
     /**
  * Paste plugin, handles BeforePaste event and reformat some special content, including:
  * 1. Content copied from Word
@@ -8764,6 +8895,8 @@ class EditPlugin implements EditorPlugin  {
      * handleTabKey: A boolean that enables or disables Tab key handling. Defaults to true.
      */
     constructor(options?: EditOptions);
+    private createNormalEnterChecker;
+    private getHandleNormalEnter;
     /**
      * Get name of this plugin
      */
@@ -8814,6 +8947,13 @@ type EditOptions = {
      * @default true
      */
     handleExpandedSelectionOnDelete?: boolean;
+    /**
+     * Callback function to determine whether the Rooster should handle the Enter key press.
+     * If the function returns true, the Rooster will handle the Enter key press instead of the browser.
+     * @param editor - The editor instance.
+     * @returns A boolean
+     */
+    shouldHandleEnterKey?: ((editor: IEditor) => boolean) | boolean;
 };
 
     /**
@@ -8862,10 +9002,13 @@ class AutoFormatPlugin implements EditorPlugin  {
      * @param event The event to handle:
      */
     onPluginEvent(event: PluginEvent): void;
+    private autoLink;
+    private tabFeatures;
     private features;
+    private enterFeatures;
+    private handleKeyboardEvents;
     private handleEditorInputEvent;
     private handleKeyDownEvent;
-    private handleEnterKey;
     private handleContentChangedEvent;
 }