feat(live-region-element): update assertive announcements to no longer work with delayMs (#51)

* feat(live-region-element): update assertive announcements to no longer work with delayMs

* chore: add changeset

Author: joshblack

.changeset/nice-terms-develop.md

@@ -0,0 +1,5 @@
+---
+"@primer/live-region-element": minor
+---
+
+Update delayMs to only work with politeness="polite"

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

@@ -105,7 +105,7 @@ describe('live-region-element', () => {
       ).toBe(Ordering.Greater)
     })
 
-    test('messages with different politeness, a scheduled at same time as b', () => {
+    test('messages with different politeness', () => {
       const now = Date.now()
       expect(
         compareMessages(
@@ -122,41 +122,5 @@ describe('live-region-element', () => {
         ),
       ).toBe(Ordering.Less)
     })
-
-    test('messages with different politeness, a scheduled before b', () => {
-      const now = Date.now()
-      expect(
-        compareMessages(
-          {
-            contents: 'test',
-            politeness: 'assertive',
-            scheduled: now,
-          },
-          {
-            contents: 'test',
-            politeness: 'polite',
-            scheduled: now + 1000,
-          },
-        ),
-      ).toBe(Ordering.Less)
-    })
-
-    test('messages with different politeness, a scheduled after b', () => {
-      const now = Date.now()
-      expect(
-        compareMessages(
-          {
-            contents: 'test',
-            politeness: 'assertive',
-            scheduled: now + 1000,
-          },
-          {
-            contents: 'test',
-            politeness: 'polite',
-            scheduled: now,
-          },
-        ),
-      ).toBe(Ordering.Greater)
-    })
   })
 })

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

@@ -3,24 +3,29 @@ import {Ordering, type Order} from './order'
 
 type Politeness = 'polite' | 'assertive'
 
-type AnnounceOptions = {
-  /**
-   * A delay in milliseconds to wait before announcing a message.
-   */
-  delayMs?: number
-
-  /**
-   * The politeness level for a message.
-   *
-   * Note: a politeness level of `assertive` should only be used for
-   * time-sensistive or critical notifications that absolutely require the
-   * user's immediate attention
-   *
-   * @see https://www.w3.org/TR/wai-aria/#aria-live
-   * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
-   */
-  politeness?: Politeness
-}
+type AnnounceOptions =
+  | {
+      /**
+       * The politeness level for a message.
+       *
+       * Note: a politeness level of `assertive` should only be used for
+       * time-sensistive or critical notifications that absolutely require the
+       * user's immediate attention
+       *
+       * @see https://www.w3.org/TR/wai-aria/#aria-live
+       * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions
+       */
+      politeness?: 'assertive'
+
+      /**
+       * A delay in milliseconds to wait before announcing a message.
+       */
+      delayMs?: never
+    }
+  | {
+      politeness?: 'polite'
+      delayMs?: number
+    }
 
 type Message = {
   contents: string
@@ -262,33 +267,14 @@ export function compareMessages(a: Message, b: Message): Order {
     return Ordering.Greater
   }
 
-  // Only prioritize assertive messages if they are scheduled at the same time,
-  // or before
+  // Assertive messages have no delay and should always have priority over
+  // non-assertive messages
   if (a.politeness === 'assertive' && b.politeness !== 'assertive') {
-    if (a.scheduled === b.scheduled) {
-      return Ordering.Less
-    }
-
-    if (a.scheduled < b.scheduled) {
-      return Ordering.Less
-    }
-
-    return Ordering.Greater
+    return Ordering.Less
   }
 
   if (a.politeness !== 'assertive' && b.politeness === 'assertive') {
-    // Schedule a after b
-    if (a.scheduled === b.scheduled) {
-      return Ordering.Greater
-    }
-
-    // Schedule a after b
-    if (a.scheduled > b.scheduled) {
-      return Ordering.Greater
-    }
-
-    // Schedule a before b
-    return Ordering.Less
+    return Ordering.Greater
   }
 
   return Ordering.Equal