@lightningjs/blits 1.35.5 → 1.36.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v1.36.0
+
+_11 Aug 2025_
+
+- Added `passFocus` option to route options to prevent focus being passed to page navigated to
+- Added missing type definitions for Route options
+- Fixed sidebar in docs
+- Added debug log messages to Announcer
+- Added `remove()` function as (preferred) alias for announcer `message.cancel()`
+- Fixed issue with removing a messages causing an interrupt of current message being read out
+
 ## v1.35.5
 
 _06 Aug 2025_

package/index.d.ts

@@ -187,7 +187,30 @@ declare module '@lightningjs/blits' {
 
   // todo: specify valid route options
   export interface RouteOptions {
-    [key: string]: any
+    /**
+     * Whether the page navigation should be added to the history stack
+     * used when navigating back using `this.$router.back()`
+     *
+     * @default true
+     */
+    inHistory?: Boolean
+    /**
+     * Whether the page should be kept alive when navigating away. Can be useful
+     * for a homepage where the state should be fully retained when navigating back
+     * from a details page
+     *
+     * @default false
+     */
+    keepAlive?: Boolean
+    /**
+     * Whether the focus should be delegated to the page that's being navigated to.
+     * Can be useful when navigating to a new page from a widget / menu overlaying the
+     * RouterView, where the widget should maintain the focus (instead of the new page, which
+     * is the default behaviour)
+     *
+     * @default true
+     */
+    passFocus?: Boolean
   }
 
   export interface Router {
@@ -628,7 +651,7 @@ declare module '@lightningjs/blits' {
     /**
      * Extra route options
      */
-    options?: object // todo: specify which options are available,
+    options?: RouteOptions
     /**
      * Message to be announced when visiting the route (often used for accessibility purposes)
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.35.5",
+  "version": "1.36.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {

package/src/announcer/announcer.js

@@ -15,6 +15,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Log } from '../lib/log.js'
 import speechSynthesis from './speechSynthesis.js'
 
 let active = false
@@ -28,6 +29,7 @@ const noopAnnouncement = {
   then() {},
   done() {},
   cancel() {},
+  remove() {},
   stop() {},
 }
 
@@ -66,11 +68,11 @@ const addToQueue = (message, politeness, delay = false) => {
     resolveFn = resolve
   })
 
-  // augment the promise with a cancel function
-  done.cancel = () => {
+  // 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)
-    isProcessing = false
+    Log.debug(`Announcer - removed from queue: "${message}" (id: ${id})`)
     resolveFn('canceled')
   }
 
@@ -92,6 +94,8 @@ const addToQueue = (message, politeness, delay = false) => {
     queue.push({ delay, resolveFn, id })
   }
 
+  Log.debug(`Announcer - added to queue: "${message}" (id: ${id})`)
+
   setTimeout(() => {
     processQueue()
   }, 100)
@@ -118,17 +122,22 @@ const processQueue = async () => {
     if (debounce !== null) clearTimeout(debounce)
     // add some easing when speaking the messages to reduce stuttering
     debounce = setTimeout(() => {
+      Log.debug(`Announcer - speaking: "${message}" (id: ${id})`)
+
       speechSynthesis
-        .speak({ message })
+        .speak({ message, id })
         .then(() => {
-          isProcessing = false
+          Log.debug(`Announcer - finished speaking: "${message}" (id: ${id})`)
+
           currentId = null
+          isProcessing = false
           resolveFn('finished')
           processQueue()
         })
         .catch((e) => {
-          isProcessing = false
           currentId = null
+          isProcessing = false
+          Log.debug(`Announcer - error ("${e.error}") while speaking: "${message}" (id: ${id})`)
           resolveFn(e.error)
           processQueue()
         })

package/src/announcer/speechSynthesis.js

@@ -64,7 +64,7 @@ const initialize = () => {
 
 const speak = (options) => {
   const utterance = new SpeechSynthesisUtterance(options.message)
-  const id = Date.now() + Math.random() // Unique ID for tracking
+  const id = options.id
   utterance.lang = options.lang || defaultUtteranceProps.lang
   utterance.pitch = options.pitch || defaultUtteranceProps.pitch
   utterance.rate = options.rate || defaultUtteranceProps.rate

package/src/router/router.js

@@ -340,8 +340,10 @@ export const navigate = async function () {
       const children = this[symbols.children]
       this.activeView = children[children.length - 1]
 
-      // set focus to the view that we're routing to
-      focus ? focus.$focus() : /** @type {BlitsComponent} */ (view).$focus()
+      // 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()
+      }
 
       // apply before settings to holder element
       if (route.transition.before) {