roosterjs 9.1.0 → 9.2.0

package/dist/rooster.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
 
@@ -1480,6 +1480,10 @@ interface ContentModelEntity extends ContentModelBlockBase<'Entity', ContentMode
  * Content Model document entry point
  */
 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;
 }
 
     /**
@@ -2864,6 +2868,11 @@ 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;
 }
 
     /**
@@ -2957,6 +2966,12 @@ 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;
 }
 
     /**
@@ -3123,6 +3138,12 @@ 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;
 }
 
     /**
@@ -3241,6 +3262,13 @@ type GetVisibleViewport = (core: EditorCore) => Rect | null;
  */
 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
+ */
+type Announce = (core: EditorCore, announceData: AnnounceData) => void;
+
     /**
  * Core plugins for editor
  */
@@ -3477,6 +3505,16 @@ 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
      */
@@ -3780,6 +3818,10 @@ 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;
 }
 
     /**
@@ -4475,6 +4517,14 @@ 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;
 }
 
     /**
@@ -4856,7 +4906,7 @@ 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;
 }
@@ -5494,9 +5544,25 @@ function addDelimiters(doc: Document, element: HTMLElement, format?: ContentMode
     /**
  * 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
  */
-function isEntityDelimiter(element: HTMLElement): boolean;
+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
+ */
+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
+ */
+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
@@ -5727,6 +5793,29 @@ function normalizeSingleSegment(segment: ContentModelSegment, ignoreTrailingSpac
  */
 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"
+ */
+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
+ */
+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
@@ -5962,12 +6051,12 @@ function getFirstSelectedTable(model: ContentModelDocument): [ContentModelTable
 
     /**
  * 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
  */
-function getOperationalBlocks<T extends ContentModelBlockGroup>(model: ContentModelDocument, blockGroupTypes: TypeOfBlockGroup<T>[], stopTypes: ContentModelBlockGroupType[], deepFirst?: boolean): OperationalBlocks<T>[];
+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
@@ -5987,7 +6076,7 @@ function getSelectedSegments(model: ContentModelDocument, includingFormatHolder:
  * @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
  */
-function getSelectedSegmentsAndParagraphs(model: ContentModelDocument, includingFormatHolder: boolean): [ContentModelSegment, ContentModelParagraph | null][];
+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
@@ -6157,7 +6246,7 @@ function updateListMetadata(list: ContentModelWithDataset<ListMetadataFormat>, c
     /**
  * Metadata definition for List
  */
-const ListMetadataDefinition: import("roosterjs-content-model-types").ObjectDefinition<ListMetadataFormat>;
+const ListMetadataDefinition: ObjectDefinition<ListMetadataFormat>;
 
     /**
  * Possible change sources. Here are the predefined sources.
@@ -6217,6 +6306,10 @@ const ChangeSource: {
      * Data of this event will be the key code number
      */
     Keyboard: string;
+    /**
+     * Content changed by auto format
+     */
+    AutoFormat: string;
 };
 
     /**
@@ -6620,6 +6713,11 @@ 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
@@ -7063,8 +7161,9 @@ function formatSegmentWithContentModel(editor: IEditor, apiName: string, toggleS
  * 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
  */
-function formatTextSegmentBeforeSelectionMarker(editor: IEditor, callback: (model: ContentModelDocument, previousSegment: ContentModelText, paragraph: ContentModelParagraph, markerFormat: ContentModelSegmentFormat, context: FormatContentModelContext) => boolean): void;
+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
@@ -7093,7 +7192,7 @@ function setModelListStartNumber(model: ContentModelDocument, value: number): bo
  * @param currentItem The current list item
  * Search for all list items in the same thread as the current list item
  */
-function findListItemsInSameThread(model: ContentModelDocument, currentItem: ContentModelListItem): ContentModelListItem[];
+function findListItemsInSameThread(group: ContentModelBlockGroup, currentItem: ContentModelListItem): ContentModelListItem[];
 
     /**
  * @param model The content model to set indentation
@@ -7101,7 +7200,7 @@ function findListItemsInSameThread(model: ContentModelDocument, currentItem: Con
  * @param length The length of indentation in pixel, default value is 40
  * Set indentation for selected list items or paragraphs
  */
-function setModelIndentation(model: ContentModelDocument, indentation: 'indent' | 'outdent', length?: number): boolean;
+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
@@ -7115,11 +7214,19 @@ function setModelIndentation(model: ContentModelDocument, indentation: 'indent'
  */
 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
+ */
+function getListAnnounceData(path: ContentModelBlockGroup[]): AnnounceData | null;
+
     /**
  * TableEdit plugin, provides the ability to resize a table by drag-and-drop
  */
 class TableEditPlugin implements EditorPlugin  {
     private anchorContainerSelector?;
+    private onTableEditorCreated?;
     private editor;
     private onMouseMoveDisposer;
     private tableRectMap;
@@ -7129,8 +7236,9 @@ 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
      */
@@ -7162,6 +7270,11 @@ class TableEditPlugin implements EditorPlugin  {
     private ensureTableRects;
 }
 
+    /**
+ * Optional callback when creating a TableEditPlugin, allows to customize the Selectors element as required.
+ */
+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
@@ -7257,6 +7370,8 @@ 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);
     /**
@@ -7295,23 +7410,31 @@ 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;
 };
 
     /**
@@ -7364,6 +7487,14 @@ const ShortcutUndo2: ShortcutCommand;
 const ShortcutRedo: ShortcutCommand;
 
     /**
+ * Shortcut command for Redo 3
+ * Windows: Ctrl + Shift + Z
+ * MacOS: Meta + Shift + Z
+ */
+const ShortcutRedoAlt: ShortcutCommand;
+
+    /**
+ * @deprecated
  * Shortcut command for Redo 2
  * Windows: N/A
  * MacOS: Meta + Shift + Z
@@ -7727,6 +7858,261 @@ class HyperlinkPlugin implements EditorPlugin  {
  */
 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.
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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.
+ */
+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.
+ */
+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
+ */
+function getDOMInsertPointRect(doc: Document, pos: DOMInsertPoint): Rect | null;
+
     /**
  * Get dark mode color for a given color
  * @param color The color to calculate from