roosterjs 8.55.0 → 8.57.0

package/dist/rooster-amd.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for roosterjs (Version 8.55.0)
+// Type definitions for roosterjs (Version 8.57.0)
 // Generated by dts tool from roosterjs
 // Project: https://github.com/Microsoft/roosterjs
 
@@ -1307,6 +1307,22 @@ export class VListChain {
     private getLists;
 }
 
+/**
+ * Convert decimal numbers into english alphabet letters
+ * @param decimal The decimal number that needs to be converted
+ * @param isLowerCase if true the roman value will appear in lower case
+ * @returns
+ */
+export function convertDecimalsToAlpha(decimal: number, isLowerCase?: boolean): string;
+
+/**
+ * Convert decimal numbers into roman numbers
+ * @param decimal The decimal number that needs to be converted
+ * @param isLowerCase if true the roman value will appear in lower case
+ * @returns
+ */
+export function convertDecimalsToRoman(decimal: number, isLowerCase?: boolean): string;
+
 /**
  * Set the Style of a List Item provided, with the styles that the inline child elements have
  * If the child inline elements have different styles, it will not modify the styles of the list item
@@ -2956,6 +2972,10 @@ export interface DOMEventPluginState {
      * Image selection range
      */
     imageSelectionRange: ImageSelectionRange | null;
+    /**
+     * When set to true, onFocus event will not trigger reselect cached range
+     */
+    skipReselectOnFocus?: boolean;
 }
 
 /**
@@ -3101,6 +3121,29 @@ export interface CopyPastePluginState {
     allowedCustomPasteType: string[];
 }
 
+/**
+ * Known announce strings
+ */
+export const enum KnownAnnounceStrings {
+    /**
+     * String announced for a list item in a OL List
+     * @example
+     * Auto corrected, {0}
+     * Where &lcub0&rcub is the new list item bullet
+     */
+    AnnounceListItemNumbering = 1,
+    /**
+     * String announced for a list item in a UL List
+     * @example
+     * Auto corrected bullet
+     */
+    AnnounceListItemBullet = 2,
+    /**
+     * String announced when cursor is moved to the last cell in a table
+     */
+    AnnounceOnFocusLastCell = 3
+}
+
 /**
  * Command strings for Document.execCommand() API
  * https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand
@@ -3845,13 +3888,24 @@ export const enum ExperimentalFeatures {
      */
     EditWithContentModel = "EditWithContentModel",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
-     */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
-    /**
+     * @deprecated This feature is always enabled
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
     AutoFormatList = "AutoFormatList",
+    /**
+     * @deprecated This feature is always enabled
+     * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
+     */
+    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
+    /**
+     * @deprecated This feature is always enabled
+     * Paste with Content model
+     */
+    ContentModelPaste = "ContentModelPaste",
+    /**
+     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * With this feature enabled, when writing back a list item we will re-use all
      * ancestor list elements, even if they don't match the types currently in the
@@ -3863,14 +3917,6 @@ export const enum ExperimentalFeatures {
      * Delete table with Backspace key with the whole was selected with table selector
      */
     DeleteTableWithBackspace = "DeleteTableWithBackspace",
-    /**
-     * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
-     */
-    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
-    /**
-     * Paste with Content model
-     */
-    ContentModelPaste = "ContentModelPaste",
     /**
      * Disable list chain functionality
      */
@@ -5300,6 +5346,25 @@ export interface BeforeKeyboardEditingData {
 export interface CompatibleBeforeKeyboardEditingEvent extends BeforeKeyboardEditingData, BasePluginEvent<CompatiblePluginEventType.BeforeKeyboardEditing> {
 }
 
+/**
+ * Represents data, that can be used to announce text to screen reader.
+ */
+export interface AnnounceData {
+    /**
+     * @optional Default announce strings built in Rooster
+     */
+    defaultStrings?: KnownAnnounceStrings | CompatibleKnownAnnounceStrings;
+    /**
+     * @optional string to announce from this Content Changed event, will be the fallback value if default string
+     * is not provided or if it is not found in the strings map.
+     */
+    text?: string;
+    /**
+     * @optional if provided, will attempt to replace {n} with each of the values inside of the array.
+     */
+    formatStrings?: string[];
+}
+
 /**
  * This refers to a "content block" in editor that serves as a content parsing boundary
  * It is most those html block like tags, i.e. &lt;p&gt;, &lt;div&gt;, &lt;li&gt;, &lt;td&gt; etc.
@@ -5430,6 +5495,12 @@ export interface ContentChangedData {
      * @returns Related entity state array
      */
     getEntityState?: () => EntityState[];
+    /**
+     * @optional
+     * Get Announce data from this content changed event.
+     * @returns
+     */
+    getAnnounceData?: () => AnnounceData | undefined;
 }
 
 /**
@@ -7235,6 +7306,12 @@ export interface EditorCore extends PluginState  {
      * If keep it null, editor will still use original dataset-based dark mode solution.
      */
     darkColorHandler: DarkColorHandler;
+    /**
+     * A callback to be invoked when any exception is thrown during disposing editor
+     * @param plugin The plugin that causes exception
+     * @param error The error object we got
+     */
+    disposeErrorHandler?: (plugin: EditorPlugin, error: Error) => void;
 }
 
 /**
@@ -7694,6 +7771,12 @@ export interface EditorOptions {
      * Color of the border of a selectedImage. Default color: '#DB626C'
      */
     imageSelectionBorderColor?: string;
+    /**
+     * A callback to be invoked when any exception is thrown during disposing editor
+     * @param plugin The plugin that causes exception
+     * @param error The error object we got
+     */
+    disposeErrorHandler?: (plugin: EditorPlugin, error: Error) => void;
 }
 
 /**
@@ -8660,13 +8743,24 @@ export enum CompatibleExperimentalFeatures {
      */
     EditWithContentModel = "EditWithContentModel",
     /**
-     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
-     */
-    TabKeyTextFeatures = "TabKeyTextFeatures",
-    /**
+     * @deprecated This feature is always enabled
      * Trigger formatting by a especial characters. Ex: (A), 1. i).
      */
     AutoFormatList = "AutoFormatList",
+    /**
+     * @deprecated This feature is always enabled
+     * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
+     */
+    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
+    /**
+     * @deprecated This feature is always enabled
+     * Paste with Content model
+     */
+    ContentModelPaste = "ContentModelPaste",
+    /**
+     * Provide additional Tab Key Features. Requires Text Features Content Editable Features
+     */
+    TabKeyTextFeatures = "TabKeyTextFeatures",
     /**
      * With this feature enabled, when writing back a list item we will re-use all
      * ancestor list elements, even if they don't match the types currently in the
@@ -8678,14 +8772,6 @@ export enum CompatibleExperimentalFeatures {
      * Delete table with Backspace key with the whole was selected with table selector
      */
     DeleteTableWithBackspace = "DeleteTableWithBackspace",
-    /**
-     * Add entities around a Read Only  Inline entity to prevent cursor to be hidden when cursor is next of it.
-     */
-    InlineEntityReadOnlyDelimiters = "InlineEntityReadOnlyDelimiters",
-    /**
-     * Paste with Content model
-     */
-    ContentModelPaste = "ContentModelPaste",
     /**
      * Disable list chain functionality
      */
@@ -8949,6 +9035,29 @@ export enum CompatibleEntityOperation {
     UpdateEntityState = 11
 }
 
+/**
+ * Known announce strings
+ */
+export enum CompatibleKnownAnnounceStrings {
+    /**
+     * String announced for a list item in a OL List
+     * @example
+     * Auto corrected, &lcub;0&rcub;
+     * Where &lcub0&rcub is the new list item bullet
+     */
+    AnnounceListItemNumbering = 1,
+    /**
+     * String announced for a list item in a UL List
+     * @example
+     * Auto corrected bullet
+     */
+    AnnounceListItemBullet = 2,
+    /**
+     * String announced when cursor is moved to the last cell in a table
+     */
+    AnnounceOnFocusLastCell = 3
+}
+
 /**
  * The position. Mostly used for content insertion and traversing
  * On insertion, we will need to specify where we want the content to be placed (begin, end, selection or outside)
@@ -10635,6 +10744,7 @@ export class PickerPlugin<T extends PickerDataProvider = PickerDataProvider> imp
     private shouldHandleKeyUpEvent;
     private onKeyUpDomEvent;
     private onKeyDownEvent;
+    private getParentNodeIfTextNode;
     private onAndroidInputEvent;
     private calcInputLength;
     private tryRemoveNode;
@@ -10784,3 +10894,63 @@ export class AutoFormat implements EditorPlugin  {
     onPluginEvent(event: PluginEvent): void;
 }
 
+/**
+ * Announce feature keys
+ */
+export type AnnounceFeatureKey = 'announceNewListItem' | 'announceWarningOnLastTableCell';
+
+/**
+ * Represents a Announce feature used in Announce Plugin.
+ * If the Should Handle Callback returns announce data, it will be announced by using a aria-live region.
+ */
+export interface AnnounceFeature {
+    /**
+     * Whether to handle this feature, if returns Announce Data, will be announced, otherwise will do nothing.
+     * @returns
+     */
+    shouldHandle: (editor: IEditor, lastFocusedElement: HTMLElement | null) => AnnounceData | false;
+    /**
+     * Keys handled in the current event
+     */
+    keys: number[];
+}
+
+/**
+ * Announce messages to screen reader by using aria live element.
+ */
+export class Announce implements EditorPlugin  {
+    private stringsMapOrGetter?;
+    private ariaLiveElement;
+    private editor;
+    private features;
+    private lastFocusedElement;
+    constructor(stringsMapOrGetter?: Map<KnownAnnounceStrings | CompatibleKnownAnnounceStrings, string> | ((key: KnownAnnounceStrings | CompatibleKnownAnnounceStrings) => string) | undefined, skipAnnounceFeatures?: AnnounceFeatureKey[], additionalFeatures?: AnnounceFeature[]);
+    /**
+     * Get a friendly name of this plugin
+     */
+    getName(): string;
+    /**
+     * Initialize this plugin
+     * @param editor The editor instance
+     */
+    initialize(editor: IEditor): void;
+    /**
+     * Dispose this plugin
+     */
+    dispose(): void;
+    /**
+     * Handle events triggered from editor
+     * @param event PluginEvent object
+     */
+    onPluginEvent(ev: PluginEvent): void;
+    private handleFeatures;
+    protected announce(announceData: AnnounceData, editor: IEditor): void;
+    private getString;
+    /**
+     * @internal
+     * Public only for unit testing.
+     * @returns
+     */
+    getAriaLiveElement(): HTMLDivElement | undefined;
+}
+