roosterjs 9.40.0 → 9.41.0

package/dist/rooster.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 9.40.0)
+// Type definitions for roosterjs (Version 9.41.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -2354,6 +2354,10 @@ interface TableSelection extends TableSelectionCoordinates, SelectionBase<'table
      * The table that this selection is representing
      */
     table: HTMLTableElement;
+    /**
+     * Table selection info
+     */
+    tableSelectionInfo?: TableSelectionInfo;
 }
 
     /**
@@ -5430,7 +5434,54 @@ type KnownAnnounceStrings = /**
 /**
  * String announced when cursor is moved to the last cell in a table
  */
- | 'announceOnFocusLastCell';
+ | 'announceOnFocusLastCell'
+/**
+ * String announced when bold formatting is applied
+ */
+ | 'announceBoldOn'
+/**
+ * String announced when bold formatting is removed
+ */
+ | 'announceBoldOff'
+/**
+ * String announced when italic formatting is applied
+ */
+ | 'announceItalicOn'
+/**
+ * String announced when italic formatting is removed
+ */
+ | 'announceItalicOff'
+/**
+ * String announced when underline formatting is applied
+ */
+ | 'announceUnderlineOn'
+/**
+ * String announced when underline formatting is removed
+ */
+ | 'announceUnderlineOff'
+/**
+ * String announced when text is selected in the editor
+ * @example
+ * {0}, selected
+ * Where {0} is the selected text content
+ */
+ | 'selected'
+/**
+ * String announced when text is unselected in the editor.
+ * @example
+ * {0}, unselected
+ */
+ | 'unselected';
+
+    /**
+ * Options for announcing format changes
+ */
+interface AnnouncingOption {
+    /**
+     * Whether to announce the format change
+     */
+    announceFormatChange?: boolean;
+}
 
     /**
  * A handler type to convert HTML string to a trust HTML string or a DOM object
@@ -5555,6 +5606,12 @@ interface DOMHelper {
      * returns the given node
      */
     findClosestElementAncestor(node: Node, selector?: string): HTMLElement | null;
+    /**
+     * Find the closest block element ancestor from the given node within current editing scope
+     * @param startFrom The node to start the search from
+     * @returns The closest block element ancestor
+     */
+    findClosestBlockElement(startFrom: Node): HTMLElement;
     /**
      * Check if the editor has focus now
      * @returns True if the editor has focus, otherwise false
@@ -5578,6 +5635,15 @@ interface DOMHelper {
      * @param darkColorHandler Optional DarkColorHandler to retrieve dark mode colors
      */
     getContainerFormat(isInDarkMode?: boolean, darkColorHandler?: DarkColorHandler): ContentModelSegmentFormat;
+    /**
+     * Get text ranges by searching for a specific text, with options to match case and whole word.
+     * This will only search within editable elements.
+     * @param text The text to search for
+     * @param matchCase Whether to match case
+     * @param wholeWord Whether to match whole word
+     * @returns An array of Ranges that match the search criteria
+     */
+    getRangesByText(text: string, matchCase: boolean, wholeWord: boolean): Range[];
 }
 
     /**
@@ -5947,6 +6013,20 @@ interface ParagraphIndexer {
     getParagraphFromMarker(paragraphWithMarker: ReadonlyContentModelParagraph): ReadonlyContentModelParagraph | null;
 }
 
+    /**
+ * The html and text content generated by the copy/cut action
+ */
+interface TextAndHtmlContentForCopy {
+    /**
+     * The HTML Content modified by the beforeCutCopy event
+     */
+    htmlContent: HTMLDivElement;
+    /**
+     * The content model modified by the beforeCutCopy event in plain text
+     */
+    textContent: string;
+}
+
     /**
  * Editor plugin event interface
  */
@@ -6365,7 +6445,7 @@ interface DoubleClickEvent extends BasePluginDomEvent<'doubleClick', MouseEvent>
     /**
  * Editor plugin event interface
  */
-type PluginEvent = BeforeAddUndoSnapshotEvent | BeforeCutCopyEvent | BeforeDisposeEvent | BeforeKeyboardEditingEvent | BeforeLogicalRootChangeEvent | BeforePasteEvent | BeforeSetContentEvent | CompositionEndEvent | ContentChangedEvent | ContextMenuEvent | RewriteFromModelEvent | EditImageEvent | EditorReadyEvent | EnterShadowEditEvent | EntityOperationEvent | ExtractContentWithDomEvent | EditorInputEvent | KeyDownEvent | KeyPressEvent | KeyUpEvent | LeaveShadowEditEvent | LogicalRootChangedEvent | MouseDownEvent | MouseUpEvent | ScrollEvent | SelectionChangedEvent | ZoomChangedEvent | PointerDownEvent | PointerUpEvent | DoubleClickEvent;
+type PluginEvent = BeforeAddUndoSnapshotEvent | BeforeCutCopyEvent | BeforeDisposeEvent | BeforeKeyboardEditingEvent | BeforeLogicalRootChangeEvent | BeforePasteEvent | BeforeSetContentEvent | CompositionEndEvent | ContentChangedEvent | ContextMenuEvent | RewriteFromModelEvent | EditImageEvent | EditorReadyEvent | EnterShadowEditEvent | EntityOperationEvent | ExtractContentWithDomEvent | EditorInputEvent | KeyDownEvent | KeyPressEvent | KeyUpEvent | LeaveShadowEditEvent | LogicalRootChangedEvent | MouseDownEvent | MouseUpEvent | ScrollEvent | SelectionChangedEvent | ZoomChangedEvent | PointerDownEvent | PointerUpEvent | DoubleClickEvent | FindResultChangedEvent;
 
     /**
  * A type to extract data part of a plugin event type. Data part is the plugin event without eventType field.
@@ -6522,7 +6602,11 @@ type PluginEventType = /**
 /**
  * HTML double click event
  */
- | 'doubleClick';
+ | 'doubleClick'
+/**
+ * Find result changed event
+ */
+ | 'findResultChanged';
 
     /**
  * This interface represents a PluginEvent wrapping native scroll event
@@ -6582,6 +6666,24 @@ interface PointerUpEvent extends BasePluginDomEvent<'pointerUp', PointerEvent> {
     originalEvent: MouseEvent | TouchEvent;
 }
 
+    /**
+ * Represents an event that occurs when the find result changes in the editor
+ */
+interface FindResultChangedEvent extends BasePluginEvent<'findResultChanged'> {
+    /**
+     * The index of the currently marked find result
+     */
+    readonly markedIndex: number;
+    /**
+     * The array of ranges representing the current find results
+     */
+    readonly ranges: ReadonlyArray<Range>;
+    /**
+     * An alternative range to select when there is no marked result
+     */
+    readonly alternativeRange?: Range | null;
+}
+
     /**
  * Create Content Model from DOM tree in this editor
  * @param root Root element of DOM tree to create Content Model from
@@ -6912,6 +7014,17 @@ function isWhiteSpacePreserved(whiteSpace: string | undefined): boolean;
  */
 function normalizeRect(clientRect: DOMRect): Rect | null;
 
+    /**
+ * Scroll a given rectangle into view within a scroll container
+ * @param scrollContainer The container to scroll
+ * @param visibleRect The currently visible rectangle within the scroll container
+ * @param domHelper The DOM helper of the editor
+ * @param targetRect The target rectangle to scroll into view
+ * @param scrollMargin Optional margin to apply when scrolling
+ * @param preferTop Optional flag to indicate whether to prefer aligning the top or bottom of the target rect when the target rect is higher than visible rect @default false
+ */
+function scrollRectIntoView(scrollContainer: HTMLElement, visibleRect: Rect, domHelper: DOMHelper, targetRect: Rect, scrollMargin?: number, preferTop?: boolean): void;
+
     /**
  * Set a hidden property on a link element to indicate whether it is undeletable or not.
  * This is used to prevent the link from being deleted when the user tries to delete it.
@@ -7490,6 +7603,17 @@ function setImageState(element: HTMLElement, marker: string): void;
  */
 function getImageState(element: HTMLElement): string | undefined;
 
+    /**
+ * Search text from the given root element and return all ranges that match the search criteria
+ * @param root Root element to search from
+ * @param text Text to search for
+ * @param matchCase Whether to match case
+ * @param wholeWord Whether to match whole words only
+ * @param editableOnly Whether to search only in editable elements
+ * @returns Array of matching ranges
+ */
+function getRangesByText(root: HTMLElement, text: string, matchCase: boolean, wholeWord: boolean, editableOnly?: boolean): Range[];
+
     /**
  * Check if the given content model block or block group is of the expected block group type
  * @param input The object to check
@@ -7929,6 +8053,10 @@ const ChangeSource: {
      * Content changed by auto format
      */
     AutoFormat: string;
+    /**
+     * Content changed by replace
+     */
+    Replace: string;
 };
 
     /**
@@ -8433,6 +8561,15 @@ function redo(editor: IEditor): void;
  */
 function paste(editor: IEditor, clipboardData: ClipboardData, pasteTypeOrGetter?: PasteTypeOrGetter): void;
 
+    /**
+ * Get the content for the copy event
+ * @param editor The editor object
+ * @param isCut if the event cut the content.
+ * @param event the clipboard event that triggered the copy/cut
+ * @returns
+ */
+function getContentForCopy(editor: IEditor, isCut: boolean, event: ClipboardEvent): TextAndHtmlContentForCopy | null;
+
     /**
  * Insert table into editor at current selection
  * @param editor The editor instance
@@ -8496,19 +8633,19 @@ function toggleNumbering(editor: IEditor, removeMargins?: boolean): void;
  * Toggle bold style
  * @param editor The editor to operate on
  */
-function toggleBold(editor: IEditor): void;
+function toggleBold(editor: IEditor, options?: AnnouncingOption): void;
 
     /**
  * Toggle italic style
  * @param editor The editor to operate on
  */
-function toggleItalic(editor: IEditor): void;
+function toggleItalic(editor: IEditor, options?: AnnouncingOption): void;
 
     /**
  * Toggle underline style
  * @param editor The editor to operate on
  */
-function toggleUnderline(editor: IEditor): void;
+function toggleUnderline(editor: IEditor, options?: AnnouncingOption): void;
 
     /**
  * Toggle strikethrough style
@@ -8841,7 +8978,7 @@ function formatParagraphWithContentModel(editor: IEditor, apiName: string, setSt
  * @param includingFormatHolder True to also include format holder of list item when search selected segments
  * @param afterFormatCallback A callback to invoke after format is applied to all selected segments and before the change is applied to DOM tree
  */
-function formatSegmentWithContentModel(editor: IEditor, apiName: string, toggleStyleCallback: (format: ContentModelSegmentFormat, isTuringOn: boolean, segment: ShallowMutableContentModelSegment | null, paragraph: ShallowMutableContentModelParagraph | null) => void, segmentHasStyleCallback?: (format: ContentModelSegmentFormat, segment: ShallowMutableContentModelSegment | null, paragraph: ShallowMutableContentModelParagraph | null) => boolean, includingFormatHolder?: boolean, afterFormatCallback?: (model: ReadonlyContentModelDocument) => void): void;
+function formatSegmentWithContentModel(editor: IEditor, apiName: string, toggleStyleCallback: (format: ContentModelSegmentFormat, isTuringOn: boolean, segment: ShallowMutableContentModelSegment | null, paragraph: ShallowMutableContentModelParagraph | null) => void, segmentHasStyleCallback?: (format: ContentModelSegmentFormat, segment: ShallowMutableContentModelSegment | null, paragraph: ShallowMutableContentModelParagraph | null) => boolean, includingFormatHolder?: boolean, afterFormatCallback?: (model: ReadonlyContentModelDocument, isTurningOff: boolean, context: FormatContentModelContext) => void): void;
 
     /**
  * Invoke a callback to format the text segment before the selection marker using Content Model
@@ -10178,6 +10315,189 @@ class TouchPlugin implements EditorPlugin  {
     onPluginEvent(event: PluginEvent): void;
 }
 
+    /**
+ * Plugin for finding and replacing text in the editor, maintain the highlights for found and replaced text
+ */
+class FindReplacePlugin implements EditorPlugin  {
+    private context;
+    private editor;
+    private findHighlightStyle;
+    private replaceHighlightStyle;
+    /**
+     * Creates a FindReplacePlugin instance
+     * @param context FindReplaceContext to use. It will be disposed when plugin is being disposed.
+     * @param options Options for highlighting styles
+     */
+    constructor(context: FindReplaceContext, options?: FindReplaceHighlightOptions);
+    /**
+     * Get name of this plugin
+     */
+    getName(): string;
+    /**
+     * The first method that editor will call to a plugin when editor is initializing.
+     * It will pass in the editor instance, plugin should take this chance to save the
+     * editor reference so that it can call to any editor method or format API later.
+     * @param editor The editor object
+     */
+    initialize(editor: IEditor): void;
+    /**
+     * The last method that editor will call to a plugin before it is disposed.
+     * Plugin can take this chance to clear the reference to editor. After this method is
+     * called, plugin should not call to any editor method since it will result in error.
+     */
+    dispose(): void;
+    /**
+     * Core method for a plugin. Once an event happens in editor, editor will call this
+     * method of each plugin to handle the event as long as the event is not handled
+     * exclusively by another plugin.
+     * @param event The event to handle:
+     */
+    onPluginEvent(event: PluginEvent): void;
+}
+
+    /**
+ * Creates a FindReplaceContext object with default values
+ * @param win The window object
+ * @param scrollMargin Margin size (in pixels) when scrolling to a highlighted item
+ * @returns
+ */
+function createFindReplaceContext(scrollMargin?: number): FindReplaceContext;
+
+    /**
+ * Start a find operation in the editor
+ * @param editor The editor instance
+ * @param context The FindReplaceContext to use
+ * @param text The text to find
+ * @param matchCase Whether to match case
+ * @param wholeWord Whether to match whole words only
+ */
+function find(editor: IEditor, context: FindReplaceContext, text: string | null, matchCase?: boolean, wholeWord?: boolean): void;
+
+    /**
+ * Replace the currently found item or all found items in the editor
+ * @param editor The editor instance
+ * @param context The FindReplaceContext to use
+ * @param replaceText The text to replace with
+ * @param replaceAll Whether to replace all found items
+ */
+function replace(editor: IEditor, context: FindReplaceContext, replaceText: string, replaceAll?: boolean): void;
+
+    /**
+ * Move the highlight to next or previous match
+ * @param editor The editor instance
+ * @param context The FindReplaceContext to use
+ * @param forward Whether to move forward or backward
+ */
+function moveHighlight(editor: IEditor, context: FindReplaceContext, forward: boolean): void;
+
+    /**
+ * Represents a context object used by all find/replace operations
+ */
+interface FindReplaceContext {
+    /**
+     * Text to find (null means no find)
+     */
+    text: string | null;
+    /**
+     * Whether to match case when finding text
+     */
+    matchCase: boolean;
+    /**
+     * Whether to match whole word when finding text
+     */
+    wholeWord: boolean;
+    /**
+     * Ranges of found results
+     */
+    ranges: Range[];
+    /**
+     * Current marked index in the ranges array
+     */
+    markedIndex: number;
+    /**
+     * Margin size (in pixels) when scrolling to a highlighted item
+     */
+    readonly scrollMargin: number;
+    /**
+     * Highlight helper used to highlight found results
+     */
+    readonly findHighlight: HighlightHelper;
+    /**
+     * Highlight helper used to highlight the current marked result
+     */
+    readonly replaceHighlight: HighlightHelper;
+}
+
+    /**
+ * Represents a helper that manages highlights in the editor
+ */
+interface HighlightHelper {
+    /**
+     * Initialize the highlight helper
+     * @param win The window object
+     */
+    initialize(win: Window): void;
+    /**
+     * Dispose the highlight helper and clear all highlights
+     */
+    dispose(): void;
+    /**
+     * Add ranges to be highlighted
+     * @param ranges The ranges to be highlighted
+     */
+    addRanges(ranges: Range[]): void;
+    /**
+     * Clear all highlights
+     */
+    clear(): void;
+}
+
+    /**
+ * Options for creating FindReplaceContext
+ */
+interface FindReplaceHighlightOptions {
+    /**
+     * Style for highlighting found items
+     */
+    findHighlightStyle?: string;
+    /**
+     * Style for highlighting replacing items
+     */
+    replaceHighlightStyle?: string;
+}
+
+    /**
+ * AnnouncePlugin helps editor announce table selection changes for accessibility
+ */
+class AnnouncePlugin implements EditorPlugin  {
+    private editor;
+    private previousSelection;
+    /**
+     * Get name of this plugin
+     */
+    getName(): string;
+    /**
+     * The first method that editor will call to a plugin when editor is initializing.
+     * It will pass in the editor instance, plugin should take this chance to save the
+     * editor reference so that it can call to any editor method or format API later.
+     * @param editor The editor object
+     */
+    initialize(editor: IEditor): void;
+    /**
+     * The last method that editor will call to a plugin before it is disposed.
+     * Plugin can take this chance to clear the reference to editor. After this method is
+     * called, plugin should not call to any editor method since it will result in error.
+     */
+    dispose(): void;
+    /**
+     * Core method for a plugin. Once an event happens in editor, editor will call this
+     * method of each plugin to handle the event as long as the event is not handled
+     * exclusively by another plugin.
+     * @param event The event to handle:
+     */
+    onPluginEvent(event: PluginEvent): void;
+}
+
     /**
  * Get dark mode color for a given color
  * @param color The color to calculate from