roosterjs 9.1.0 → 9.2.0

package/dist/rooster-amd.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 9.1.0)
+// Type definitions for roosterjs (Version 9.2.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -1479,6 +1479,10 @@ export interface ContentModelEntity extends ContentModelBlockBase<'Entity', Cont
  * Content Model document entry point
  */
 export interface ContentModelDocument extends ContentModelBlockGroupBase<'Document'>, Partial<ContentModelWithFormat<ContentModelSegmentFormat>> {
+    /**
+     * Whether the selection in model (if any) is a revert selection (end is before start)
+     */
+    hasRevertedRangeSelection?: boolean;
 }
 
 /**
@@ -2863,6 +2867,11 @@ export interface IEditor {
      * combined with root selector together to build a separate rule.
      */
     setEditorStyle(key: string, cssRule: string | null, subSelectors?: 'before' | 'after' | string[]): void;
+    /**
+     * Announce the given data
+     * @param announceData Data to announce
+     */
+    announce(announceData: AnnounceData): void;
 }
 
 /**
@@ -2956,6 +2965,12 @@ export interface EditorOptions {
      * Default paste type. By default will use the normal (as-is) paste type.
      */
     defaultPasteType?: PasteType;
+    /**
+     * A callback to help get string template to announce, used for accessibility
+     * @param key The key of known announce data
+     * @returns A template string to announce, use placeholder such as "{0}" for variables if necessary
+     */
+    announcerStringGetter?: (key: KnownAnnounceStrings) => string;
 }
 
 /**
@@ -3122,6 +3137,12 @@ export interface CoreApiMap {
      * combined with root selector together to build a separate rule.
      */
     setEditorStyle: SetEditorStyle;
+    /**
+     * Announce the given data
+     * @param core The EditorCore object
+     * @param announceData Data to announce
+     */
+    announce: Announce;
 }
 
 /**
@@ -3240,6 +3261,13 @@ export type GetVisibleViewport = (core: EditorCore) => Rect | null;
  */
 export type SetEditorStyle = (core: EditorCore, key: string, cssRule: string | null, subSelectors?: 'before' | 'after' | string[], maxRuleLength?: number) => void;
 
+/**
+ * Announce the given data
+ * @param core The EditorCore object
+ * @param announceData Data to announce
+ */
+export type Announce = (core: EditorCore, announceData: AnnounceData) => void;
+
 /**
  * Core plugins for editor
  */
@@ -3476,6 +3504,16 @@ export interface LifecyclePluginState {
      * Cached document fragment for original content
      */
     shadowEditFragment: DocumentFragment | null;
+    /**
+     * The HTML container for announced string
+     */
+    announceContainer?: HTMLElement;
+    /**
+     * A callback to help get string template to announce, used for accessibility
+     * @param key The key of known announce data
+     * @returns A template string to announce, use placeholder such as "{0}" for variables if necessary
+     */
+    readonly announcerStringGetter?: (key: KnownAnnounceStrings) => string;
     /**
      * Style elements used for adding CSS rules for editor
      */
@@ -3779,6 +3817,10 @@ export interface FormatContentModelContext {
      * @optional Set to true if this action can be undone when user press Backspace key (aka Auto Complete).
      */
     canUndoByBackspace?: boolean;
+    /**
+     * @optional Set this value to tell AnnouncePlugin to announce the given information
+     */
+    announceData?: AnnounceData | null;
 }
 
 /**
@@ -4474,6 +4516,14 @@ export interface DOMHelper {
      * @returns True if the editor has focus, otherwise false
      */
     hasFocus(): boolean;
+    /**
+     * Check if the root element is in RTL mode
+     */
+    isRightToLeft(): boolean;
+    /**
+     * Get the width of the editable area of the editor content div
+     */
+    getClientWidth(): number;
 }
 
 /**
@@ -4855,7 +4905,7 @@ export interface ContentChangedEvent extends BasePluginEvent<'contentChanged'> {
      */
     readonly formatApiName?: string;
     /**
-     * @optional Announce data from this content changed event.
+     * @deprecated Call editor.announce(announceData) directly insteaad
      */
     readonly announceData?: AnnounceData;
 }
@@ -5493,9 +5543,25 @@ export function addDelimiters(doc: Document, element: HTMLElement, format?: Cont
 /**
  * Checks whether the node provided is a Entity delimiter
  * @param node the node to check
+ * @param isBefore True to match delimiter before entity only, false to match delimiter after entity, or undefined means match both
  * @return true if it is a delimiter
  */
-export function isEntityDelimiter(element: HTMLElement): boolean;
+export function isEntityDelimiter(element: HTMLElement, isBefore?: boolean): boolean;
+
+/**
+ * Check if the given element is a container element of block entity
+ * @param element The element to check
+ * @returns True if the element is a block entity container, otherwise false
+ */
+export function isBlockEntityContainer(element: HTMLElement): boolean;
+
+/**
+ * Find the closest block entity wrapper element from a given DOM node
+ * @param node The node to start looking for entity container
+ * @param domHelper The DOM helper
+ * @returns
+ */
+export function findClosestBlockEntityContainer(node: Node, domHelper: DOMHelper): HTMLElement | null;
 
 /**
  * When set a DOM tree into editor, reuse the existing element in editor and no need to change it
@@ -5726,6 +5792,29 @@ export function normalizeSingleSegment(segment: ContentModelSegment, ignoreTrail
  */
 export function setParagraphNotImplicit(block: ContentModelBlock): void;
 
+/**
+ * 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
+ * @param listNumber List number, start from 1
+ * @returns A string for this list item. For example, when pass in NumberingListType.LowerAlpha and 2, it returns "b"
+ */
+export function getOrderedListNumberStr(styleType: number, listNumber: number): string;
+
+/**
+ * Get automatic list style of a list item according to its lis type and metadata.
+ * @param listType The list type, either OL or UL
+ * @param metadata Metadata of this list item from list item model
+ * @param depth Depth of list level, start from 0
+ * @param existingStyleType Existing list style type in format, if any
+ * @returns A number to represent list style type.
+ * This will be the value of either NumberingListType (when listType is OL) or BulletListType (when listType is UL).
+ * When there is a specified list style in its metadata, return this value, otherwise
+ * When specified "applyListStyleFromLevel" in metadata, calculate auto list type from its depth, otherwise
+ * When there is already listStyleType in list level format, find a related style type index, otherwise
+ * return undefined
+ */
+export function getAutoListStyleType(listType: 'OL' | 'UL', metadata: ListMetadataFormat, depth: number, existingStyleType?: string): number | undefined;
+
 /**
  * Parse unit value with its unit
  * @param value The source value to parse
@@ -5961,12 +6050,12 @@ export function getFirstSelectedTable(model: ContentModelDocument): [ContentMode
 
 /**
  * Get an array of block group - block pair that is of the expected block group type from selection
- * @param model The Content Model to get selection from
+ * @param group The root block group to search
  * @param blockGroupTypes The expected block group types
  * @param stopTypes Block group types that will stop searching when hit
  * @param deepFirst True means search in deep first, otherwise wide first
  */
-export function getOperationalBlocks<T extends ContentModelBlockGroup>(model: ContentModelDocument, blockGroupTypes: TypeOfBlockGroup<T>[], stopTypes: ContentModelBlockGroupType[], deepFirst?: boolean): OperationalBlocks<T>[];
+export function getOperationalBlocks<T extends ContentModelBlockGroup>(group: ContentModelBlockGroup, blockGroupTypes: TypeOfBlockGroup<T>[], stopTypes: ContentModelBlockGroupType[], deepFirst?: boolean): OperationalBlocks<T>[];
 
 /**
  * Get any array of selected paragraphs from a content model
@@ -5986,7 +6075,7 @@ export function getSelectedSegments(model: ContentModelDocument, includingFormat
  * @param model The Content Model to get selection from
  * @param includingFormatHolder True means also include format holder as segment from list item, in that case paragraph will be null
  */
-export function getSelectedSegmentsAndParagraphs(model: ContentModelDocument, includingFormatHolder: boolean): [ContentModelSegment, ContentModelParagraph | null][];
+export function getSelectedSegmentsAndParagraphs(model: ContentModelDocument, includingFormatHolder: boolean, includingEntity?: boolean): [ContentModelSegment, ContentModelParagraph | null, ContentModelBlockGroup[]][];
 
 /**
  * Get selection coordinates of a table. If there is no selection, return null
@@ -6156,7 +6245,7 @@ export function updateListMetadata(list: ContentModelWithDataset<ListMetadataFor
 /**
  * Metadata definition for List
  */
-export const ListMetadataDefinition: import("roosterjs-content-model-types").ObjectDefinition<ListMetadataFormat>;
+export const ListMetadataDefinition: ObjectDefinition<ListMetadataFormat>;
 
 /**
  * Possible change sources. Here are the predefined sources.
@@ -6216,6 +6305,10 @@ export const ChangeSource: {
      * Data of this event will be the key code number
      */
     Keyboard: string;
+    /**
+     * Content changed by auto format
+     */
+    AutoFormat: string;
 };
 
 /**
@@ -6619,6 +6712,11 @@ export class Editor implements IEditor  {
      * combined with root selector together to build a separate rule.
      */
     setEditorStyle(key: string, cssRule: string | null, subSelectors?: 'before' | 'after' | string[]): void;
+    /**
+     * Announce the given data
+     * @param announceData Data to announce
+     */
+    announce(announceData: AnnounceData): void;
     /**
      * @returns the current EditorCore object
      * @throws a standard Error if there's no core object
@@ -7062,8 +7160,9 @@ export function formatSegmentWithContentModel(editor: IEditor, apiName: string,
  * Invoke a callback to format the text segment before the selection marker using Content Model
  * @param editor The editor object
  * @param callback The callback to format the text segment.
+ * @returns True if the segment before cursor is found and callback is called, otherwise false
  */
-export function formatTextSegmentBeforeSelectionMarker(editor: IEditor, callback: (model: ContentModelDocument, previousSegment: ContentModelText, paragraph: ContentModelParagraph, markerFormat: ContentModelSegmentFormat, context: FormatContentModelContext) => boolean): void;
+export function formatTextSegmentBeforeSelectionMarker(editor: IEditor, callback: (model: ContentModelDocument, previousSegment: ContentModelText, paragraph: ContentModelParagraph, markerFormat: ContentModelSegmentFormat, context: FormatContentModelContext) => boolean, options?: FormatContentModelOptions): boolean;
 
 /**
  * Set a list type to content model
@@ -7092,7 +7191,7 @@ export function setModelListStartNumber(model: ContentModelDocument, value: numb
  * @param currentItem The current list item
  * Search for all list items in the same thread as the current list item
  */
-export function findListItemsInSameThread(model: ContentModelDocument, currentItem: ContentModelListItem): ContentModelListItem[];
+export function findListItemsInSameThread(group: ContentModelBlockGroup, currentItem: ContentModelListItem): ContentModelListItem[];
 
 /**
  * @param model The content model to set indentation
@@ -7100,7 +7199,7 @@ export function findListItemsInSameThread(model: ContentModelDocument, currentIt
  * @param length The length of indentation in pixel, default value is 40
  * Set indentation for selected list items or paragraphs
  */
-export function setModelIndentation(model: ContentModelDocument, indentation: 'indent' | 'outdent', length?: number): boolean;
+export function setModelIndentation(model: ContentModelDocument, indentation: 'indent' | 'outdent', length?: number, context?: FormatContentModelContext): boolean;
 
 /**
  * Try to match a given string with link match rules, return matched link
@@ -7114,11 +7213,19 @@ export function setModelIndentation(model: ContentModelDocument, indentation: 'i
  */
 export function matchLink(url: string): LinkData | null;
 
+/**
+ * Get announce data for list item
+ * @param path Content model path that include the list item
+ * @returns Announce data of current list item if any, or null
+ */
+export function getListAnnounceData(path: ContentModelBlockGroup[]): AnnounceData | null;
+
 /**
  * TableEdit plugin, provides the ability to resize a table by drag-and-drop
  */
 export class TableEditPlugin implements EditorPlugin  {
     private anchorContainerSelector?;
+    private onTableEditorCreated?;
     private editor;
     private onMouseMoveDisposer;
     private tableRectMap;
@@ -7128,8 +7235,9 @@ export class TableEditPlugin implements EditorPlugin  {
      * @param anchorContainerSelector An optional selector string to specify the container to host the plugin.
      * The container must not be affected by transform: scale(), otherwise the position calculation will be wrong.
      * If not specified, the plugin will be inserted in document.body
+     * @param onTableEditorCreated An optional callback to customize the Table Editors elements when created.
      */
-    constructor(anchorContainerSelector?: string | undefined);
+    constructor(anchorContainerSelector?: string | undefined, onTableEditorCreated?: OnTableEditorCreatedCallback | undefined);
     /**
      * Get a friendly name of this plugin
      */
@@ -7161,6 +7269,11 @@ export class TableEditPlugin implements EditorPlugin  {
     private ensureTableRects;
 }
 
+/**
+ * Optional callback when creating a TableEditPlugin, allows to customize the Selectors element as required.
+ */
+export type OnTableEditorCreatedCallback = (editorType: 'HorizontalTableInserter' | 'VerticalTableInserter' | 'TableMover' | 'TableResizer', element: HTMLElement) => () => void;
+
 /**
  * Paste plugin, handles BeforePaste event and reformat some special content, including:
  * 1. Content copied from Word
@@ -7256,6 +7369,8 @@ export class AutoFormatPlugin implements EditorPlugin  {
      *  - autoLink: A boolean that enables or disables automatic hyperlink creation when pasting or typing content. Defaults to false.
      *  - autoUnlink: A boolean that enables or disables automatic hyperlink removal when pressing backspace. Defaults to false.
      *  - autoHyphen: A boolean that enables or disables automatic hyphen transformation. Defaults to false.
+     *  - autoFraction: A boolean that enables or disables automatic fraction transformation. Defaults to false.
+     *  - autoOrdinals: A boolean that enables or disables automatic ordinal number transformation. Defaults to false.
      */
     constructor(options?: AutoFormatOptions);
     /**
@@ -7294,23 +7409,31 @@ export type AutoFormatOptions = {
     /**
      * When true, after type *, ->, -, --, => , —, > and space key a type of bullet list will be triggered. @default true
      */
-    autoBullet: boolean;
+    autoBullet?: boolean;
     /**
      * When true, after type 1, A, a, i, I followed by ., ), - or between () and space key a type of numbering list will be triggered. @default true
      */
-    autoNumbering: boolean;
+    autoNumbering?: boolean;
     /**
      * When press backspace before a link, remove the hyperlink
      */
-    autoUnlink: boolean;
+    autoUnlink?: boolean;
     /**
      * When paste content, create hyperlink for the pasted link
      */
-    autoLink: boolean;
+    autoLink?: boolean;
     /**
      * Transform -- into hyphen, if typed between two words
      */
-    autoHyphen: boolean;
+    autoHyphen?: boolean;
+    /**
+     * Transform 1/2, 1/4, 3/4 into fraction character
+     */
+    autoFraction?: boolean;
+    /**
+     * Transform ordinal numbers into superscript
+     */
+    autoOrdinals?: boolean;
 };
 
 /**
@@ -7363,6 +7486,14 @@ export const ShortcutUndo2: ShortcutCommand;
 export const ShortcutRedo: ShortcutCommand;
 
 /**
+ * Shortcut command for Redo 3
+ * Windows: Ctrl + Shift + Z
+ * MacOS: Meta + Shift + Z
+ */
+export const ShortcutRedoAlt: ShortcutCommand;
+
+/**
+ * @deprecated
  * Shortcut command for Redo 2
  * Windows: N/A
  * MacOS: Meta + Shift + Z
@@ -7726,6 +7857,261 @@ export class HyperlinkPlugin implements EditorPlugin  {
  */
 export type HyperlinkToolTip = string | null | ((url: string, anchor: HTMLAnchorElement) => string);
 
+/**
+ * PickerPlugin represents a plugin of editor which can handle picker related behaviors, including
+ * - Show picker when special trigger key is pressed
+ * - Hide picker
+ * - Change selection in picker by Up/Down/Left/Right
+ * - Apply selected item in picker
+ *
+ * PickerPlugin doesn't provide any UI, it just wraps related DOM events and invoke callback functions.
+ */
+export class PickerPlugin implements EditorPlugin  {
+    private triggerCharacter;
+    private readonly handler;
+    private isMac;
+    private lastQueryString;
+    private helper;
+    /**
+     * Construct a new instance of PickerPlugin class
+     * @param triggerCharacter The character to trigger a picker to be shown
+     * @param handler Picker handler for receiving picker state change events
+     */
+    constructor(triggerCharacter: string, handler: PickerHandler);
+    /**
+     * Get a friendly name
+     */
+    getName(): string;
+    /**
+     * Initialize this plugin. This should only be called from Editor
+     * @param editor Editor instance
+     */
+    initialize(editor: IEditor): void;
+    /**
+     * Dispose this plugin
+     */
+    dispose(): void;
+    /**
+     * Check if the plugin should handle the given event exclusively.
+     * Handle an event exclusively means other plugin will not receive this event in
+     * onPluginEvent method.
+     * If two plugins will return true in willHandleEventExclusively() for the same event,
+     * the final result depends on the order of the plugins are added into editor
+     * @param event The event to check
+     */
+    willHandleEventExclusively(event: PluginEvent): boolean;
+    /**
+     * Handle events triggered from editor
+     * @param event PluginEvent object
+     */
+    onPluginEvent(event: PluginEvent): void;
+    private onSuggestingKeyDown;
+    private onSuggestingInput;
+    private onInput;
+}
+
+/**
+ * Represents the interface of picker plugin, provides necessary utility functions for pickers
+ */
+export interface PickerHelper {
+    /**
+     * The editor instance
+     */
+    readonly editor: IEditor;
+    /**
+     * Replace the query string with a given Content Model.
+     * This is used for commit a change from picker and insert the committed content into editor.
+     * @param model The Content Model to insert
+     * @param options Options for formatting content model
+     * @param canUndoByBackspace Whether this change can be undone using Backspace key
+     */
+    replaceQueryString: (model: ContentModelDocument, options?: FormatContentModelOptions, canUndoByBackspace?: boolean) => void;
+    /**
+     * Notify Picker Plugin that picker is closed from the handler code, so picker plugin can quit the suggesting state
+     */
+    closePicker: () => void;
+}
+
+/**
+ * Change mode that PickerPlugin will pass to child class
+ */
+export type PickerSelectionChangMode = /**
+ * When user press Right ("horizontal" mode or "both" mode) (Left in RTL) or Down ("vertical" mode),
+ * select the next option
+ */
+'next'
+/**
+ * When user press Left ("horizontal" mode or "both" mode) (Right in RTL) or Up ("vertical" mode),
+ * select the previous option
+ */
+ | 'previous'
+/**
+ * When user press Down ("both" mode),
+ * select the next row
+ */
+ | 'nextRow'
+/**
+ * When user press Up ("both" mode),
+ * select the previous row
+ */
+ | 'previousRow'
+/**
+ * When user press PageDown,
+ * switch to next page
+ */
+ | 'nextPage'
+/**
+ * When user press PageUp,
+ * switch to previous page
+ */
+ | 'previousPage'
+/**
+ * When user press Home,
+ * Select the first item in current row
+ */
+ | 'firstInRow'
+/**
+ * When user press End,
+ * Select the last item in current row
+ */
+ | 'lastInRow'
+/**
+ * When user press CTRL (or META on Mac) + Home,
+ * Select the very first item
+ */
+ | 'first'
+/**
+ * When user press CTRL (or META on Mac) + End,
+ * Select the very last item
+ */
+ | 'last';
+
+/**
+ * Direction option for picker
+ */
+export type PickerDirection = /**
+ * Show options horizontally
+ */
+'horizontal'
+/**
+ * Show options vertically
+ */
+ | 'vertical'
+/**
+ * Show options in both direction (2-D picker)
+ */
+ | 'both';
+
+/**
+ * Represents the interface a handler for picker plugin. Developer need to implement this interface to create a new type of picker
+ */
+export interface PickerHandler {
+    /**
+     * Initialize the picker handler, pass in editor and PickerPlugin instance so that the handler can save them
+     * @param editor The editor instance
+     * @param pickerPlugin The PickerPlugin instance
+     */
+    onInitialize: (helper: PickerHelper) => void;
+    /**
+     * Dispose the picker handler
+     */
+    onDispose: () => void;
+    /**
+     * Notify the picker handler that user has typed trigger character so handler should show picker now
+     * @param queryString Current query string
+     * @param insertPoint Insert point where user is typing, can be used for calculating picker position
+     * @returns A picker direction to let picker plugin know what kind of picker is opened. Picker plugin will use this value
+     * to decide how to handle keyboard event to change selection. Return null means picker is not actually opened
+     */
+    onTrigger: (queryString: string, insertPoint: DOMInsertPoint) => PickerDirection | null;
+    /**
+     * Notify the picker handler that picker should be closed now
+     */
+    onClosePicker?(): void;
+    /**
+     * Notify the picker handler that user has changed current typed query string
+     */
+    onQueryStringChanged?(queryString: string): void;
+    /**
+     * Notify the picker handler that user has decide to select the current option in picker
+     */
+    onSelect?(): void;
+    /**
+     * Notify the picker handler that user is using keyboard to change current selection
+     * @param mode The moving mode. Handler code can use this value to decide which item need to be selected
+     */
+    onSelectionChanged?(mode: PickerSelectionChangMode): void;
+}
+
+/**
+ * CustomReplacePlugin is a plugin that allows you to replace a string with another string in the editor.
+ */
+export class CustomReplacePlugin implements EditorPlugin  {
+    private customReplacements;
+    private editor;
+    private triggerKeys;
+    /**
+     * @param customReplacements Custom replacement rules.
+     * Ex: [{ stringToReplace: ':)', replacementString: '🙂', replacementHandler: replaceEmojis }]
+     */
+    constructor(customReplacements: CustomReplace[]);
+    /**
+     * 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;
+    private handleEditorInputEvent;
+}
+
+/**
+ * The CustomReplace interface defines a custom replacement that can be used in CustomReplacePlugin.
+ */
+export interface CustomReplace {
+    /**
+     * The string to replace in the editor.
+     */
+    stringToReplace: string;
+    /**
+     * The string to replace with.
+     */
+    replacementString: string;
+    /**
+     * The handler to replace the string.
+     * @param previousSegment The text segment to replace.
+     * @param stringToReplace The string to replace.
+     * @param replacementString The string to replace with.
+     * @param paragraph The paragraph that contains the text segment.
+     * @returns True if the string is replaced successfully, otherwise false.
+     */
+    replacementHandler: (previousSegment: ContentModelText, stringToReplace: string, replacementString: string, paragraph?: ContentModelParagraph) => boolean;
+}
+
+/**
+ * Get bounding rect of the given DOM insert point
+ * @param doc The document object
+ * @param pos The input DOM insert point
+ */
+export function getDOMInsertPointRect(doc: Document, pos: DOMInsertPoint): Rect | null;
+
 /**
  * Get dark mode color for a given color
  * @param color The color to calculate from