roosterjs 9.40.0 → 9.41.0

package/dist/rooster-amd.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
 
@@ -2353,6 +2353,10 @@ export interface TableSelection extends TableSelectionCoordinates, SelectionBase
      * The table that this selection is representing
      */
     table: HTMLTableElement;
+    /**
+     * Table selection info
+     */
+    tableSelectionInfo?: TableSelectionInfo;
 }
 
 /**
@@ -5429,7 +5433,54 @@ export 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
+ */
+export 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
@@ -5554,6 +5605,12 @@ export 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
@@ -5577,6 +5634,15 @@ export 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[];
 }
 
 /**
@@ -5946,6 +6012,20 @@ export interface ParagraphIndexer {
     getParagraphFromMarker(paragraphWithMarker: ReadonlyContentModelParagraph): ReadonlyContentModelParagraph | null;
 }
 
+/**
+ * The html and text content generated by the copy/cut action
+ */
+export 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
  */
@@ -6364,7 +6444,7 @@ export interface DoubleClickEvent extends BasePluginDomEvent<'doubleClick', Mous
 /**
  * Editor plugin event interface
  */
-export 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;
+export 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.
@@ -6521,7 +6601,11 @@ export type PluginEventType = /**
 /**
  * HTML double click event
  */
- | 'doubleClick';
+ | 'doubleClick'
+/**
+ * Find result changed event
+ */
+ | 'findResultChanged';
 
 /**
  * This interface represents a PluginEvent wrapping native scroll event
@@ -6581,6 +6665,24 @@ export interface PointerUpEvent extends BasePluginDomEvent<'pointerUp', PointerE
     originalEvent: MouseEvent | TouchEvent;
 }
 
+/**
+ * Represents an event that occurs when the find result changes in the editor
+ */
+export 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
@@ -6911,6 +7013,17 @@ export function isWhiteSpacePreserved(whiteSpace: string | undefined): boolean;
  */
 export 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
+ */
+export 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.
@@ -7489,6 +7602,17 @@ export function setImageState(element: HTMLElement, marker: string): void;
  */
 export 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
+ */
+export 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
@@ -7928,6 +8052,10 @@ export const ChangeSource: {
      * Content changed by auto format
      */
     AutoFormat: string;
+    /**
+     * Content changed by replace
+     */
+    Replace: string;
 };
 
 /**
@@ -8432,6 +8560,15 @@ export function redo(editor: IEditor): void;
  */
 export 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
+ */
+export function getContentForCopy(editor: IEditor, isCut: boolean, event: ClipboardEvent): TextAndHtmlContentForCopy | null;
+
 /**
  * Insert table into editor at current selection
  * @param editor The editor instance
@@ -8495,19 +8632,19 @@ export function toggleNumbering(editor: IEditor, removeMargins?: boolean): void;
  * Toggle bold style
  * @param editor The editor to operate on
  */
-export function toggleBold(editor: IEditor): void;
+export function toggleBold(editor: IEditor, options?: AnnouncingOption): void;
 
 /**
  * Toggle italic style
  * @param editor The editor to operate on
  */
-export function toggleItalic(editor: IEditor): void;
+export function toggleItalic(editor: IEditor, options?: AnnouncingOption): void;
 
 /**
  * Toggle underline style
  * @param editor The editor to operate on
  */
-export function toggleUnderline(editor: IEditor): void;
+export function toggleUnderline(editor: IEditor, options?: AnnouncingOption): void;
 
 /**
  * Toggle strikethrough style
@@ -8840,7 +8977,7 @@ export function formatParagraphWithContentModel(editor: IEditor, apiName: string
  * @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
  */
-export 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;
+export 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
@@ -10177,6 +10314,189 @@ export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export function moveHighlight(editor: IEditor, context: FindReplaceContext, forward: boolean): void;
+
+/**
+ * Represents a context object used by all find/replace operations
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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