feat: add support for dynamic insert, await for messages (#86)

* feat: add support for dynamic insert, await for messages

* chore: add changesets

* chore: address eslint violations

Author: joshblack

.changeset/healthy-queens-learn.md

@@ -0,0 +1,5 @@
+---
+"@primer/live-region-element": minor
+---
+
+Add support for waiting for announcement completion by returning a promise from announce, announceFromElement

.changeset/poor-dingos-jog.md

@@ -0,0 +1,5 @@
+---
+"@primer/live-region-element": minor
+---
+
+Add support for dynamically inserting live regions while still announcing to screen readers

.eslintrc.cjs

@@ -29,6 +29,7 @@ const config = {
   rules: {
     'no-unused-vars': 'off',
     'import/no-unresolved': 'off',
+    'eslint-comments/no-use': 'off',
   },
   overrides: [
     {

packages/live-region-element/src/Deferred.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, github/no-then */
+
+export class Deferred<T = void> implements Promise<T> {
+  [Symbol.toStringTag] = 'Deferred'
+
+  #promise: Promise<T>
+  #resolve!: (value: T | PromiseLike<T>) => void
+  #reject!: (reason?: any) => void
+
+  constructor() {
+    this.#promise = new Promise<T>((resolve, reject) => {
+      this.#resolve = resolve
+      this.#reject = reject
+    })
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,
+  ): Promise<TResult1 | TResult2> {
+    return Promise.prototype.then.apply(this.#promise, [onfulfilled, onrejected]) as Promise<TResult1 | TResult2>
+  }
+
+  catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined,
+  ): Promise<T | TResult> {
+    return Promise.prototype.catch.apply(this.#promise, [onrejected])
+  }
+
+  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+    return Promise.prototype.finally.apply(this.#promise, [onfinally])
+  }
+
+  resolve(value: T) {
+    this.#resolve(value)
+  }
+
+  reject(reason?: any) {
+    this.#reject(reason)
+  }
+
+  getPromise(): Promise<T> {
+    return this.#promise
+  }
+}

packages/live-region-element/src/__tests__/live-region-element.test.ts

@@ -1,18 +1,21 @@
-import {afterEach, beforeEach, describe, test, expect} from 'vitest'
+import {afterEach, beforeEach, describe, test, expect, vi} from 'vitest'
 import {LiveRegionElement, compareMessages} from '../live-region-element'
 import {Ordering} from '../order'
+import {Deferred} from '../Deferred'
 import '../define'
 
 describe('live-region-element', () => {
   let liveRegion: LiveRegionElement
 
   beforeEach(() => {
+    vi.useFakeTimers()
     liveRegion = document.createElement('live-region') as LiveRegionElement
     document.body.appendChild(liveRegion)
   })
 
   afterEach(() => {
     document.body.removeChild(liveRegion)
+    vi.restoreAllMocks()
   })
 
   test('announce() message', () => {
@@ -33,6 +36,51 @@ describe('live-region-element', () => {
     expect(liveRegion.getMessage('assertive')).toBe('test')
   })
 
+  test('announce() with delayMs', () => {
+    liveRegion.announce('test', {
+      delayMs: 1000,
+    })
+    expect(liveRegion.getMessage('polite')).toBe('')
+    vi.runAllTimers()
+    expect(liveRegion.getMessage('polite')).toBe('test')
+  })
+
+  test('cancel announce() with delayMs', () => {
+    const {cancel} = liveRegion.announce('test', {
+      delayMs: 1000,
+    })
+    expect(liveRegion.getMessage('polite')).toBe('')
+
+    cancel()
+    vi.runAllTimers()
+
+    expect(liveRegion.getMessage('polite')).toBe('')
+  })
+
+  test('await announce()', async () => {
+    const announcement = liveRegion.announce('test', {
+      delayMs: 1000,
+    })
+    expect(liveRegion.getMessage('polite')).toBe('')
+
+    vi.runAllTimers()
+    await announcement
+    expect(liveRegion.getMessage('polite')).toBe('test')
+  })
+
+  test('cancel await announce()', async () => {
+    const announcement = liveRegion.announce('test', {
+      delayMs: 1000,
+    })
+    expect(liveRegion.getMessage('polite')).toBe('')
+
+    vi.advanceTimersByTime(500)
+    announcement.cancel()
+    vi.runAllTimers()
+    await announcement
+    expect(liveRegion.getMessage('polite')).toBe('')
+  })
+
   test('announceFromElement()', () => {
     const element = document.createElement('div')
     element.textContent = 'test'
@@ -59,11 +107,13 @@ describe('live-region-element', () => {
             contents: 'test',
             politeness: 'polite',
             scheduled: now,
+            deferred: new Deferred(),
           },
           {
             contents: 'test',
             politeness: 'polite',
             scheduled: now,
+            deferred: new Deferred(),
           },
         ),
       ).toBe(Ordering.Equal)
@@ -77,11 +127,13 @@ describe('live-region-element', () => {
             contents: 'test',
             politeness: 'polite',
             scheduled: now,
+            deferred: new Deferred(),
           },
           {
             contents: 'test',
             politeness: 'polite',
             scheduled: now + 1000,
+            deferred: new Deferred(),
           },
         ),
       ).toBe(Ordering.Less)
@@ -95,11 +147,13 @@ describe('live-region-element', () => {
             contents: 'test',
             politeness: 'polite',
             scheduled: now + 1000,
+            deferred: new Deferred(),
           },
           {
             contents: 'test',
             politeness: 'polite',
             scheduled: now,
+            deferred: new Deferred(),
           },
         ),
       ).toBe(Ordering.Greater)
@@ -113,11 +167,13 @@ describe('live-region-element', () => {
             contents: 'test',
             politeness: 'assertive',
             scheduled: now,
+            deferred: new Deferred(),
           },
           {
             contents: 'test',
             politeness: 'polite',
             scheduled: now,
+            deferred: new Deferred(),
           },
         ),
       ).toBe(Ordering.Less)