@lightningjs/blits 1.35.5 → 1.37.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.37.0
+
+_22 Aug 2025_
+
+- Added Route options check before checking passFocus flag
+- Added support for additional metadata in Route config (for associating arbitrary data to a route)
+- Upgraded dev dependencies to latest versions
+
+## 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/eslint.config.cjs

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2023 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 {
+    defineConfig,
+    globalIgnores,
+} = require("eslint/config");
+
+const globals = require("globals");
+const prettier = require("eslint-plugin-prettier");
+const babelParser = require("@babel/eslint-parser");
+const js = require("@eslint/js");
+
+const {
+    FlatCompat,
+} = require("@eslint/eslintrc");
+
+const compat = new FlatCompat({
+    baseDirectory: __dirname,
+    recommendedConfig: js.configs.recommended,
+    allConfig: js.configs.all
+});
+
+module.exports = defineConfig([{
+    languageOptions: {
+        globals: {
+            ...globals.browser,
+            ...globals.node,
+            globalThis: false,
+        },
+
+        parser: babelParser,
+        ecmaVersion: 2018,
+        sourceType: "module",
+
+        parserOptions: {
+            requireConfigFile: false,
+
+            babelOptions: {
+                plugins: ["@babel/plugin-syntax-import-assertions"],
+            },
+        },
+    },
+
+    plugins: {
+        prettier,
+    },
+
+    extends: compat.extends("eslint:recommended", "plugin:prettier/recommended", "prettier"),
+
+    rules: {
+        "no-console": process.env.NODE_ENV === "production" ? "error" : "off",
+        "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
+        quotes: [2, "single", "avoid-escape"],
+        semi: [2, "never"],
+        "no-extra-boolean-cast": "off",
+
+        "no-unused-vars": [1, {
+            argsIgnorePattern: "res|next|^err",
+        }],
+
+        "prettier/prettier": ["error", {
+            trailingComma: "es5",
+            singleQuote: true,
+            tabWidth: 2,
+            semi: false,
+            printWidth: 100,
+            endOfLine: "auto",
+        }],
+    },
+}, globalIgnores(["**/node_modules"])]);

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)
      *
@@ -656,6 +679,17 @@ declare module '@lightningjs/blits' {
     data?: {
       [key: string]: any
     }
+
+    /**
+     * Metadata attached to the route, can be used to add any arbitrary
+     * data to a route such as `auth: true/false`, a route ID or route description
+     * Note that this data is not reactive and not passed as props to components.
+     * The metadata is available in the router `before` or `beforeEach` hooks
+     *
+     */
+    meta?: {
+      [key: string]: any
+    }
   }
 
   type ComponentFactory = () => void

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.35.5",
+  "version": "1.37.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -35,16 +35,19 @@
   "devDependencies": {
     "@babel/eslint-parser": "^7.26.5",
     "@babel/plugin-syntax-import-assertions": "^7.26.0",
-    "c8": "^8.0.1",
-    "eslint": "^8.8.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.33.0",
+    "c8": "^9.1.0",
+    "eslint": "^9.33.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
     "fast-glob": "^3.3.3",
     "global-jsdom": "24.0.0",
+    "globals": "^16.3.0",
     "husky": "^9.1.7",
     "jsdom": "24.0.0",
     "lint-staged": "^15.5.0",
-    "prettier": "^2.5.1",
+    "prettier": "^3.6.2",
     "sinon": "^21.0.0",
     "tap-diff": "^0.1.1",
     "tape": "^5.5.0"

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/application.js

@@ -96,9 +96,12 @@ const Application = (config) => {
 
       Focus.input(key, e)
       clearTimeout(holdTimeout)
-      holdTimeout = setTimeout(() => {
-        Focus.hold = true
-      }, Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS))
+      holdTimeout = setTimeout(
+        () => {
+          Focus.hold = true
+        },
+        Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS)
+      )
     }
 
     keyUpHandler = (e) => {

package/src/component/setup/props.js

@@ -41,8 +41,8 @@ export default (component, props = []) => {
           this[symbols.props] !== undefined && prop.key in this[symbols.props]
             ? this[symbols.props][prop.key]
             : 'default' in prop
-            ? prop.default
-            : undefined
+              ? prop.default
+              : undefined
         )
 
         if (prop.required === true && value === undefined) {

package/src/engines/L3/element.js

@@ -107,8 +107,8 @@ const layoutFn = function (config) {
             ? node.height + gap
             : 0
           : node.height !== 0
-          ? node.height + gap
-          : 0
+            ? node.height + gap
+            : 0
     }
     otherDimension = Math.max(
       otherDimension,

package/src/lib/codegenerator/generator.js

@@ -191,9 +191,9 @@ const generateElementCode = function (
       } else {
         this.effectsCode.push(`
             ${elm}.set('${key.substring(1)}', ${interpolate(
-          templateObject[key],
-          options.component
-        )})
+              templateObject[key],
+              options.component
+            )})
           `)
       }
       // value.includes('.') === false &&
@@ -310,9 +310,9 @@ const generateComponentCode = function (
     if (isReactiveKey(key)) {
       this.effectsCode.push(`
         ${elm}[Symbol.for('props')]['${key.substring(1)}'] = ${interpolate(
-        templateObject[key],
-        options.component
-      )}`)
+          templateObject[key],
+          options.component
+        )}`)
       renderCode.push(`
         propData = ${interpolate(templateObject[key], options.component)}
         if (Array.isArray(propData) === true) {

package/src/plugins/language.js

@@ -41,8 +41,8 @@ export default {
         Object.keys(translations).length === 0
           ? 'No translations loaded. Please load a file with translations or specify a translations object manually'
           : language in translations === false
-          ? `Language ${language} not available in the loaded translations`
-          : false
+            ? `Language ${language} not available in the loaded translations`
+            : false
       if (warningMsg) {
         Log.warn(warningMsg)
         // set the current language in the reactive state
@@ -127,12 +127,15 @@ export default {
           return Object.keys(
             // maps array input to an object {0: 'item1', 1: 'item2'}
             Array.isArray(replacements) ? Object.assign({}, replacements) : replacements
-          ).reduce((text, replacementKey) => {
-            return text.replace(
-              new RegExp('{\\s?' + replacementKey + '\\s?}', 'g'),
-              replacements[replacementKey]
-            )
-          }, (dictionary && dictionary[key]) || key)
+          ).reduce(
+            (text, replacementKey) => {
+              return text.replace(
+                new RegExp('{\\s?' + replacementKey + '\\s?}', 'g'),
+                replacements[replacementKey]
+              )
+            },
+            (dictionary && dictionary[key]) || key
+          )
         }
       },
       get language() {

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 === undefined || route.options.passFocus !== false) {
+        focus ? focus.$focus() : /** @type {BlitsComponent} */ (view).$focus()
+      }
 
       // apply before settings to holder element
       if (route.transition.before) {