@lightningjs/blits 2.8.9 → 2.9.0

package/CHANGELOG.md

@@ -1,7 +1,16 @@
 # Changelog
 
+## 2.9.0
+
+_9 sep 2026_
+
+- Added DOM based Aria announcer implementation
+
+
 ## 2.8.9
 
+_12 aug 2026_
+
 - Fixed focus issue related to multiple named router views
 
 ## 2.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.8.9",
+  "version": "2.9.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -36,6 +36,10 @@
       "types": "./src/platforms/webOS/announcer.d.ts",
       "default": "./src/platforms/webOS/announcer.js"
     },
+    "./platforms/dom/announcer": {
+      "types": "./src/platforms/dom/announcer.d.ts",
+      "default": "./src/platforms/dom/announcer.js"
+    },
     "./testing": {
       "types": "./src/testing/index.d.ts",
       "default": "./src/testing/index.js"

package/src/announcer/announcer.js

@@ -81,15 +81,30 @@ const addToQueue = (message, politeness, delay = false, options = {}) => {
 
   // setup a promise to allow developer to chain functionality
   // when specific utterances are done
-  let resolveFn
+  let resolvePromise
+  let settled = false
   const done = new Promise((resolve) => {
-    resolveFn = resolve
+    resolvePromise = resolve
   })
 
+  const resolveFn = (status) => {
+    if (settled === true) return
+    settled = true
+    resolvePromise(status)
+  }
+
   // augment the promise with a cancel / remove function
   done.remove = done.cancel = () => {
     const index = queue.findIndex((item) => item.id === id)
-    if (index !== -1) queue.splice(index, 1)
+    if (index !== -1) {
+      queue.splice(index, 1)
+    } else if (id === currentId && debounce !== null) {
+      clearDebounceTimer()
+      currentId = null
+      currentResolveFn = null
+      isProcessing = false
+      processQueue()
+    }
     Log.debug(`Announcer - removed from queue: "${message}" (id: ${id})`)
     resolveFn('canceled')
   }

package/src/platforms/dom/announcer.d.ts

@@ -0,0 +1,28 @@
+import type { AnnouncerDriver } from '@lightningjs/blits'
+
+export interface DOMAnnouncerOptions {
+  /**
+   * Document in which the live region is created. Defaults to the global document.
+   */
+  document?: Document | null
+  /**
+   * Element that receives the live region. Defaults to document.body.
+   */
+  container?: HTMLElement
+  /**
+   * ID used to find or create the single live region.
+   *
+   * @default 'blits-announcer'
+   */
+  id?: string
+  /**
+   * Delay between clearing the region and inserting the next message.
+   *
+   * @default 0
+   */
+  updateDelay?: number
+}
+
+declare function createAnnouncer(options?: DOMAnnouncerOptions): AnnouncerDriver
+
+export default createAnnouncer

package/src/platforms/dom/announcer.js

@@ -0,0 +1,111 @@
+/*
+ * Copyright 2026 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const globalScope = globalThis
+const defaultId = 'blits-announcer'
+
+const visuallyHiddenStyles = {
+  position: 'absolute',
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  margin: '-1px',
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: '0',
+}
+
+const createAnnouncer = (options = {}) => {
+  const documentRef = Object.prototype.hasOwnProperty.call(options, 'document')
+    ? options.document
+    : globalScope.document
+  const id = options.id || defaultId
+  const updateDelay = options.updateDelay === undefined ? 0 : options.updateDelay
+
+  let region
+  let pendingUpdate
+
+  const getRegion = () => {
+    if (!documentRef || typeof documentRef.createElement !== 'function') return
+    if (region && region.isConnected !== false) return region
+
+    region = typeof documentRef.getElementById === 'function' && documentRef.getElementById(id)
+
+    if (!region) {
+      const parent = options.container || documentRef.body || documentRef.documentElement
+      if (!parent || typeof parent.appendChild !== 'function') return
+
+      region = documentRef.createElement('div')
+      region.id = id
+      parent.appendChild(region)
+    }
+
+    Object.assign(region.style, visuallyHiddenStyles)
+    region.setAttribute('role', 'alert')
+    region.setAttribute('aria-live', 'assertive')
+    region.setAttribute('aria-atomic', 'true')
+
+    return region
+  }
+
+  const cancelPendingUpdate = (error = 'canceled') => {
+    if (pendingUpdate === undefined) return
+    clearTimeout(pendingUpdate.timer)
+    pendingUpdate.reject({ error })
+    pendingUpdate = undefined
+  }
+
+  // Create the empty region before the first announcement so assistive
+  // technology can observe subsequent content changes reliably.
+  getRegion()
+
+  return {
+    speak(announcement) {
+      if (!announcement || announcement.message === undefined || announcement.message === null) {
+        return Promise.reject({ error: 'Missing message' })
+      }
+
+      const liveRegion = getRegion()
+      if (!liveRegion) {
+        return Promise.reject({ error: 'unavailable' })
+      }
+
+      cancelPendingUpdate()
+      liveRegion.textContent = ''
+
+      return new Promise((resolve, reject) => {
+        const update = {
+          reject,
+          timer: setTimeout(() => {
+            if (pendingUpdate !== update) return
+            liveRegion.textContent = String(announcement.message)
+            pendingUpdate = undefined
+            resolve()
+          }, updateDelay),
+        }
+        pendingUpdate = update
+      })
+    },
+    cancel() {
+      cancelPendingUpdate()
+      if (region) region.textContent = ''
+    },
+  }
+}
+
+export default createAnnouncer