@lightningjs/blits 2.8.8 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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
 
 _11 aug 2026_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.8.8",
+  "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/focus/focus.js

@@ -20,7 +20,7 @@ import { state } from '../router/router.js'
 import Settings from '../settings.js'
 import { DEFAULT_HOLD_TIMEOUT_MS } from '../constants.js'
 import { Log } from '../lib/log.js'
-import { getAncestors } from './helpers.js'
+import { getAncestors, isInAliveComponentTree } from './helpers.js'
 import { platform } from '../platform.js'
 
 let focusedComponent = null
@@ -41,7 +41,7 @@ export default {
     return focusedComponent
   },
   set(component, event) {
-    if (component === undefined || component.eol === true) return
+    if (component === undefined || isInAliveComponentTree(component) === false) return
 
     clearTimeout(setFocusTimeout)
 

package/src/focus/helpers.js

@@ -29,3 +29,22 @@ export const getAncestors = (components) => {
   }
   return components
 }
+
+/**
+ * Checks whether a component and its ancestors are alive. When root is provided,
+ * the component must also belong to that root's tree.
+ * @param {Object|undefined|null} component
+ * @param {Object|undefined|null} [root]
+ * @returns {boolean}
+ */
+export const isInAliveComponentTree = (component, root) => {
+  let current = component
+
+  while (current !== undefined && current !== null) {
+    if (current.eol === true) return false
+    if (root !== undefined && current === root) return true
+    current = current[symbols.parent]
+  }
+
+  return root === undefined
+}

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

package/src/router/router.js

@@ -22,6 +22,7 @@ import symbols from '../lib/symbols.js'
 import { Log } from '../lib/log.js'
 import { stage } from '../launch.js'
 import Focus from '../focus/focus.js'
+import { isInAliveComponentTree } from '../focus/helpers.js'
 import Announcer from '../announcer/announcer.js'
 import Settings from '../settings.js'
 import { platform } from '../platform.js'
@@ -80,6 +81,20 @@ export const state = reactive(
 const history = []
 const routerViews = new Set()
 let singleRouterView = null
+let activeNavigations = 0
+
+const startNavigation = () => {
+  if (activeNavigations++ === 0) {
+    state.navigating = true
+  }
+}
+
+const finishNavigation = () => {
+  activeNavigations--
+  if (activeNavigations === 0) {
+    state.navigating = false
+  }
+}
 
 // Per-RouterView navigation state keyed by router view name.
 // When multiple router views exist, each view must have its own navigation
@@ -124,9 +139,17 @@ export const navigate = async function () {
   if (!this[symbols.parent][symbols.routes] || this[symbols.parent][symbols.routes].length === 0)
     return
 
-  if (this.history === undefined) this.history = []
+  startNavigation()
 
-  state.navigating = true
+  try {
+    await performNavigation.call(this, viewState)
+  } finally {
+    finishNavigation()
+  }
+}
+
+const performNavigation = async function (viewState) {
+  if (this.history === undefined) this.history = []
 
   Announcer.stop()
   Announcer.clear()
@@ -142,8 +165,6 @@ export const navigate = async function () {
 
   // early return when route not found
   if (route === false) {
-    state.navigating = false
-
     Log.error(`Route ${hash.hash} not found`)
     const routerHooks = this[symbols.parent][symbols.routerHooks]
     if (routerHooks && typeof routerHooks.error === 'function') {
@@ -154,7 +175,6 @@ export const navigate = async function () {
 
   // sameRouteObject is too simple check for now!
   if (this.currentRoute !== undefined && sameRouteObject(route, this.currentRoute)) {
-    state.navigating = false
     return
   }
 
@@ -176,7 +196,6 @@ export const navigate = async function () {
   )
   if (beforeEachResult === false) {
     viewState.preventHashChangeNavigation = false
-    state.navigating = false
     return
   }
 
@@ -193,7 +212,6 @@ export const navigate = async function () {
   )
   if (beforeResult === false) {
     viewState.preventHashChangeNavigation = false
-    state.navigating = false
     return
   }
 
@@ -313,7 +331,9 @@ export const navigate = async function () {
 
   // set focus to the view that we're routing to (unless explicitly disabling passing focus)
   if (route.options.passFocus !== false) {
-    focus ? focus.$focus() : /** @type {BlitsComponent} */ (view).$focus()
+    isInAliveComponentTree(focus, view)
+      ? /** @type {BlitsComponent} */ (focus).$focus()
+      : /** @type {BlitsComponent} */ (view).$focus()
   }
 
   // apply starting state of transition
@@ -400,7 +420,6 @@ export const navigate = async function () {
 
   // reset navigating indicators
   viewState.navigatingBack = false
-  state.navigating = false
   viewState.preventHashChangeNavigation = false
 }
 
@@ -451,7 +470,6 @@ const executeBeforeHook = async function (
         platform.historyBack()
 
         viewState.navigatingBack = false
-        state.navigating = false
       }
       return false
     }
@@ -468,7 +486,6 @@ const executeBeforeHook = async function (
         viewState.preventHashChangeNavigation = true
         platform.historyBack()
         viewState.navigatingBack = false
-        state.navigating = false
       }
       return false
     }