Port AnnouncePlugin Step 2: Add announce core API

packages/roosterjs-content-model-core/lib/coreApi/announce/announce.ts

@@ -0,0 +1,60 @@
+import type { Announce } from 'roosterjs-content-model-types';
+
+/**
+ * @internal
+ * Announce the given data
+ * @param core The EditorCore object
+ * @param announceData Data to announce
+ */
+export const announce: Announce = (core, announceData) => {
+    const { text, defaultStrings, formatStrings = [] } = announceData;
+    const { announcerStringGetter } = core.lifecycle;
+    const template = defaultStrings && announcerStringGetter?.(defaultStrings);
+    const textToAnnounce = formatString(template || text, formatStrings);
+
+    if (textToAnnounce) {
+        let announceContainer = core.lifecycle.announceContainer;
+
+        if (!announceContainer || textToAnnounce == announceContainer.textContent) {
+            announceContainer?.parentElement?.removeChild(announceContainer);
+            announceContainer = createAriaLiveElement(core.physicalRoot.ownerDocument);
+
+            core.lifecycle.announceContainer = announceContainer;
+        }
+
+        if (announceContainer) {
+            announceContainer.textContent = textToAnnounce;
+        }
+    }
+};
+
+function formatString(text: string | undefined, formatStrings: string[]) {
+    if (text == undefined) {
+        return text;
+    }
+
+    text = text.replace(/\{(\d+)\}/g, (_, sub: string) => {
+        const index = parseInt(sub);
+        const replace = formatStrings[index];
+        return replace ?? '';
+    });
+
+    return text;
+}
+
+function createAriaLiveElement(document: Document): HTMLDivElement {
+    const div = document.createElement('div');
+
+    div.style.clip = 'rect(0px, 0px, 0px, 0px)';
+    div.style.clipPath = 'inset(100%)';
+    div.style.height = '1px';
+    div.style.overflow = 'hidden';
+    div.style.position = 'absolute';
+    div.style.whiteSpace = 'nowrap';
+    div.style.width = '1px';
+    div.ariaLive = 'assertive';
+
+    document.body.appendChild(div);
+
+    return div;
+}

packages/roosterjs-content-model-core/lib/coreApi/coreApiMap.ts

@@ -1,5 +1,5 @@
-import type { CoreApiMap } from 'roosterjs-content-model-types';
 import { addUndoSnapshot } from './addUndoSnapshot/addUndoSnapshot';
+import { announce } from './announce/announce';
 import { attachDomEvent } from './attachDomEvent/attachDomEvent';
 import { createContentModel } from './createContentModel/createContentModel';
 import { createEditorContext } from './createEditorContext/createEditorContext';
@@ -14,6 +14,7 @@ import { setEditorStyle } from './setEditorStyle/setEditorStyle';
 import { setLogicalRoot } from './setLogicalRoot/setLogicalRoot';
 import { switchShadowEdit } from './switchShadowEdit/switchShadowEdit';
 import { triggerEvent } from './triggerEvent/triggerEvent';
+import type { CoreApiMap } from 'roosterjs-content-model-types';
 
 /**
  * @internal
@@ -39,4 +40,6 @@ export const coreApiMap: CoreApiMap = {
     switchShadowEdit: switchShadowEdit,
     getVisibleViewport: getVisibleViewport,
     setEditorStyle: setEditorStyle,
+
+    announce: announce,
 };

packages/roosterjs-content-model-core/lib/coreApi/formatContentModel/formatContentModel.ts

@@ -100,6 +100,10 @@ export const formatContentModel: FormatContentModel = (
 
         handlePendingFormat(core, context, core.api.getDOMSelection(core));
     }
+
+    if (context.announceData) {
+        core.api.announce(core, context.announceData);
+    }
 };
 
 function handleImages(core: EditorCore, context: FormatContentModelContext) {

packages/roosterjs-content-model-core/lib/corePlugin/lifecycle/LifecyclePlugin.ts

@@ -48,6 +48,7 @@ class LifecyclePlugin implements PluginWithState<LifecyclePluginState> {
             isDarkMode: !!options.inDarkMode,
             shadowEditFragment: null,
             styleElements: {},
+            announcerStringGetter: options.announcerStringGetter,
         };
     }
 
@@ -88,6 +89,13 @@ class LifecyclePlugin implements PluginWithState<LifecyclePluginState> {
             delete this.state.styleElements[key];
         });
 
+        const announceContainer = this.state.announceContainer;
+
+        if (announceContainer) {
+            announceContainer.parentElement?.removeChild(announceContainer);
+            delete this.state.announceContainer;
+        }
+
         if (this.disposer) {
             this.disposer();
             this.disposer = null;

packages/roosterjs-content-model-core/lib/editor/Editor.ts

@@ -31,6 +31,7 @@ import type {
     EntityState,
     CachedElementHandler,
     DomToModelOptionForCreateModel,
+    AnnounceData,
 } from 'roosterjs-content-model-types';
 
 /**
@@ -402,6 +403,16 @@ export class Editor implements IEditor {
         core.api.setEditorStyle(core, key, cssRule, subSelectors);
     }
 
+    /**
+     * Announce the given data
+     * @param announceData Data to announce
+     */
+    announce(announceData: AnnounceData): void {
+        const core = this.getCore();
+
+        core.api.announce(core, announceData);
+    }
+
     /**
      * @returns the current EditorCore object
      * @throws a standard Error if there's no core object

packages/roosterjs-content-model-core/test/coreApi/announce/announceTest.ts

@@ -0,0 +1,218 @@
+import { announce } from '../../../lib/coreApi/announce/announce';
+import { EditorCore } from 'roosterjs-content-model-types';
+
+describe('announce', () => {
+    let core: EditorCore;
+    let createElementSpy: jasmine.Spy;
+    let appendChildSpy: jasmine.Spy;
+    let getterSpy: jasmine.Spy;
+
+    beforeEach(() => {
+        createElementSpy = jasmine.createSpy('createElement');
+        appendChildSpy = jasmine.createSpy('appendChild');
+        getterSpy = jasmine.createSpy('getter');
+
+        core = {
+            lifecycle: {
+                announcerStringGetter: getterSpy,
+            },
+            physicalRoot: {
+                ownerDocument: {
+                    createElement: createElementSpy,
+                    body: {
+                        appendChild: appendChildSpy,
+                    },
+                },
+            },
+        } as any;
+    });
+
+    it('announce empty string', () => {
+        announce(core, {});
+        expect(createElementSpy).not.toHaveBeenCalled();
+        expect(appendChildSpy).not.toHaveBeenCalled();
+    });
+
+    it('announce a given string', () => {
+        const mockedDiv = {
+            style: {},
+        } as any;
+
+        createElementSpy.and.returnValue(mockedDiv);
+        announce(core, {
+            text: 'test',
+        });
+
+        expect(createElementSpy).toHaveBeenCalledWith('div');
+        expect(appendChildSpy).toHaveBeenCalledWith(mockedDiv);
+        expect(mockedDiv).toEqual({
+            style: {
+                clip: 'rect(0px, 0px, 0px, 0px)',
+                clipPath: 'inset(100%)',
+                height: '1px',
+                overflow: 'hidden',
+                position: 'absolute',
+                whiteSpace: 'nowrap',
+                width: '1px',
+            },
+            ariaLive: 'assertive',
+            textContent: 'test',
+        });
+    });
+
+    it('announce a default string', () => {
+        const mockedDiv = {
+            style: {},
+        } as any;
+
+        createElementSpy.and.returnValue(mockedDiv);
+        getterSpy.and.returnValue('test');
+
+        announce(core, {
+            defaultStrings: 'announceListItemBullet',
+        });
+
+        expect(getterSpy).toHaveBeenCalledWith('announceListItemBullet');
+        expect(createElementSpy).toHaveBeenCalledWith('div');
+        expect(appendChildSpy).toHaveBeenCalledWith(mockedDiv);
+        expect(mockedDiv).toEqual({
+            style: {
+                clip: 'rect(0px, 0px, 0px, 0px)',
+                clipPath: 'inset(100%)',
+                height: '1px',
+                overflow: 'hidden',
+                position: 'absolute',
+                whiteSpace: 'nowrap',
+                width: '1px',
+            },
+            ariaLive: 'assertive',
+            textContent: 'test',
+        });
+    });
+
+    it('announce a default string with format', () => {
+        const mockedDiv = {
+            style: {},
+        } as any;
+
+        createElementSpy.and.returnValue(mockedDiv);
+        getterSpy.and.returnValue('test1 {0} test2');
+
+        announce(core, {
+            defaultStrings: 'announceListItemBullet',
+            formatStrings: ['replace1', 'replace2'],
+        });
+
+        expect(getterSpy).toHaveBeenCalledWith('announceListItemBullet');
+        expect(createElementSpy).toHaveBeenCalledWith('div');
+        expect(appendChildSpy).toHaveBeenCalledWith(mockedDiv);
+        expect(mockedDiv).toEqual({
+            style: {
+                clip: 'rect(0px, 0px, 0px, 0px)',
+                clipPath: 'inset(100%)',
+                height: '1px',
+                overflow: 'hidden',
+                position: 'absolute',
+                whiteSpace: 'nowrap',
+                width: '1px',
+            },
+            ariaLive: 'assertive',
+            textContent: 'test1 replace1 test2',
+        });
+    });
+
+    it('announce a default string with complex format', () => {
+        const mockedDiv = {
+            style: {},
+        } as any;
+
+        createElementSpy.and.returnValue(mockedDiv);
+        getterSpy.and.returnValue('test1 {0} test2 {1} {0}');
+
+        announce(core, {
+            defaultStrings: 'announceListItemBullet',
+            formatStrings: ['replace1', 'replace2'],
+        });
+
+        expect(getterSpy).toHaveBeenCalledWith('announceListItemBullet');
+        expect(createElementSpy).toHaveBeenCalledWith('div');
+        expect(appendChildSpy).toHaveBeenCalledWith(mockedDiv);
+        expect(mockedDiv).toEqual({
+            style: {
+                clip: 'rect(0px, 0px, 0px, 0px)',
+                clipPath: 'inset(100%)',
+                height: '1px',
+                overflow: 'hidden',
+                position: 'absolute',
+                whiteSpace: 'nowrap',
+                width: '1px',
+            },
+            ariaLive: 'assertive',
+            textContent: 'test1 replace1 test2 replace2 replace1',
+        });
+    });
+
+    it('already has div with different text', () => {
+        const removeChildSpy = jasmine.createSpy('removeChild');
+        const mockedDiv = {
+            textContent: '',
+            parentElement: {
+                removeChild: removeChildSpy,
+            },
+        } as any;
+
+        core.lifecycle.announceContainer = mockedDiv;
+
+        createElementSpy.and.returnValue(mockedDiv);
+        announce(core, {
+            text: 'test',
+        });
+
+        expect(removeChildSpy).not.toHaveBeenCalled();
+        expect(createElementSpy).not.toHaveBeenCalled();
+        expect(appendChildSpy).not.toHaveBeenCalled();
+        expect(mockedDiv).toEqual({
+            textContent: 'test',
+            parentElement: {
+                removeChild: removeChildSpy,
+            },
+        });
+    });
+
+    it('already has div with same text', () => {
+        const removeChildSpy = jasmine.createSpy('removeChild');
+        const mockedDiv = {
+            textContent: 'test',
+            parentElement: {
+                removeChild: removeChildSpy,
+            },
+        } as any;
+        const mockedDiv2 = {
+            style: {},
+        } as any;
+
+        core.lifecycle.announceContainer = mockedDiv;
+        createElementSpy.and.returnValue(mockedDiv2);
+
+        announce(core, {
+            text: 'test',
+        });
+
+        expect(removeChildSpy).toHaveBeenCalledWith(mockedDiv);
+        expect(createElementSpy).toHaveBeenCalledWith('div');
+        expect(appendChildSpy).toHaveBeenCalledWith(mockedDiv2);
+        expect(mockedDiv2).toEqual({
+            style: {
+                clip: 'rect(0px, 0px, 0px, 0px)',
+                clipPath: 'inset(100%)',
+                height: '1px',
+                overflow: 'hidden',
+                position: 'absolute',
+                whiteSpace: 'nowrap',
+                width: '1px',
+            },
+            ariaLive: 'assertive',
+            textContent: 'test',
+        });
+    });
+});