@lightningjs/blits 1.31.2 → 1.32.1-rc.0

package/CHANGELOG.md

@@ -1,12 +1,23 @@
 # Changelog
 
-_30 Jun 2024_
+_02 Jul 2025_
+
+## v1.32.0
+
+- Added global router hooks `init` and `error`
+- Fixed issues with `this` scope in global router hooks
+- Fixed issue with `data` in `beforeEach` route not being complete
+- Added input throttling functionality
+- Optimized performance of children retrieval in `<Layout>`
+- Added documentation on global router hooks
+
+_30 Jun 2025_
 
 ## v1.31.1
 
 - Upgraded renderer to v2.15.0
 
-_30 Jun 2024_
+_30 Jun 2025_
 
 ## v1.31.1
 

package/index.d.ts

@@ -481,14 +481,16 @@ declare module '@lightningjs/blits' {
   }
 
   export interface RouterHooks {
+    init?: () => Promise<> | void;
     beforeEach?: (to: Route, from: Route) => string | Route | Promise<string | Route> | void;
+    error?: (err: string) => string | Route | Promise<string | Route> | void;
   }
 
-  export interface RouterConfig {
+  export interface RouterConfig<P extends Props, S, M, C> {
     /**
      * Register hooks for the router
      */
-    hooks?: RouterHooks,
+    hooks?: RouterHooks & ComponentContext<P, S, M, C>,
 
     /**
      * Routes definition
@@ -511,7 +513,7 @@ declare module '@lightningjs/blits' {
       /**
        * Router Configuration
        */
-      router?: RouterConfig,
+      router?: RouterConfig<P, S, M, C>,
       routes?: never
     }
     |
@@ -965,6 +967,17 @@ declare module '@lightningjs/blits' {
      * Defaults to `50` (ms)
      */
     holdTimeout?: number,
+    /**
+     * Input throttle time in milliseconds to prevent rapid successive inputs
+     *
+     * Within the throttle window, only one input will be processed immediately  Subsequent
+     * inputs are ignored until the scheduled input is processed.
+     *
+     * Set to `0` to disable input throttling.
+     *
+     * Defaults to `0` (disabled)
+     */
+    inputThrottle?: number,
     /**
      * Custom canvas object used to render the App to.
      *

package/package.json

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

package/src/application.js

@@ -47,6 +47,7 @@ const Application = (config) => {
   let keyDownHandler
   let keyUpHandler
   let holdTimeout
+  let lastInputTime = 0
 
   config.hooks[symbols.destroy] = function () {
     document.removeEventListener('keydown', keyDownHandler)
@@ -58,8 +59,27 @@ const Application = (config) => {
     this.$announcer.toggle(Settings.get('announcer', false))
     const keyMap = { ...defaultKeyMap, ...Settings.get('keymap', {}) }
 
+    /** @type {number} Input throttle time in milliseconds (0 = disabled) */
+    const throttleMs = Settings.get('inputThrottle', 0)
+
     keyDownHandler = async (e) => {
+      const currentTime = performance.now()
+
       const key = keyMap[e.key] || keyMap[e.keyCode] || e.key || e.keyCode
+      // execute immediately when no throttle is specified or event is internal (bubbled up by focus manager)
+      if (throttleMs === 0 || e[symbols.internalEvent] === true) {
+        return await processInput.call(this, e, key)
+      }
+
+      if (currentTime - lastInputTime < throttleMs) {
+        return
+      }
+
+      lastInputTime = currentTime
+      await processInput.call(this, e, key)
+    }
+
+    const processInput = async function (e, key) {
       // intercept key press if specified in main Application component
       if (
         this[symbols.inputEvents] !== undefined &&

package/src/components/Circle.js

@@ -50,16 +50,17 @@ export default () =>
       },
       effects: [
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('color', component.color)
+          if (elms[0] !== undefined) elms[0].set('color', component.color)
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('w', component.size)
+          if (elms[0] !== undefined) elms[0].set('w', component.size)
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('h', component.size)
+          if (elms[0] !== undefined) elms[0].set('h', component.size)
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('effects', [component.shader('radius', { radius: component.radius })])
+          if (elms[0] !== undefined)
+            elms[0].set('effects', [component.shader('radius', { radius: component.radius })])
         },
       ],
       context: {},

package/src/components/FPScounter.js

@@ -1366,84 +1366,84 @@ export default () =>
       effects: [
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip6 === 'undefined' || skip6.indexOf('frame') === -1)
-            elms[6].set('frame', component.fps[0])
+            if (elms[6] !== undefined) elms[6].set('frame', component.fps[0])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[7][Symbol.for('props')]['frame'] = component.fps[0]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip8 === 'undefined' || skip8.indexOf('frame') === -1)
-            elms[8].set('frame', component.fps[1])
+            if (elms[8] !== undefined) elms[8].set('frame', component.fps[1])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[9][Symbol.for('props')]['frame'] = component.fps[1]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip10 === 'undefined' || skip10.indexOf('frame') === -1)
-            elms[10].set('frame', component.fps[2])
+            if (elms[10] !== undefined) elms[10].set('frame', component.fps[2])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[11][Symbol.for('props')]['frame'] = component.fps[2]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip16 === 'undefined' || skip16.indexOf('frame') === -1)
-            elms[16].set('frame', component.avgFps[0])
+            if (elms[16] !== undefined) elms[16].set('frame', component.avgFps[0])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[17][Symbol.for('props')]['frame'] = component.avgFps[0]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip18 === 'undefined' || skip18.indexOf('frame') === -1)
-            elms[18].set('frame', component.avgFps[1])
+            if (elms[18] !== undefined) elms[18].set('frame', component.avgFps[1])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[19][Symbol.for('props')]['frame'] = component.avgFps[1]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip20 === 'undefined' || skip20.indexOf('frame') === -1)
-            elms[20].set('frame', component.avgFps[2])
+            if (elms[20] !== undefined) elms[20].set('frame', component.avgFps[2])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[21][Symbol.for('props')]['frame'] = component.avgFps[2]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip26 === 'undefined' || skip26.indexOf('frame') === -1)
-            elms[26].set('frame', component.minFps[0])
+            if (elms[26] !== undefined) elms[26].set('frame', component.minFps[0])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[27][Symbol.for('props')]['frame'] = component.minFps[0]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip28 === 'undefined' || skip28.indexOf('frame') === -1)
-            elms[28].set('frame', component.minFps[1])
+            if (elms[28] !== undefined) elms[28].set('frame', component.minFps[1])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[29][Symbol.for('props')]['frame'] = component.minFps[1]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip30 === 'undefined' || skip30.indexOf('frame') === -1)
-            elms[30].set('frame', component.minFps[2])
+            if (elms[30] !== undefined) elms[30].set('frame', component.minFps[2])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[31][Symbol.for('props')]['frame'] = component.minFps[2]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip36 === 'undefined' || skip36.indexOf('frame') === -1)
-            elms[36].set('frame', component.maxFps[0])
+            if (elms[36] !== undefined) elms[36].set('frame', component.maxFps[0])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[37][Symbol.for('props')]['frame'] = component.maxFps[0]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip38 === 'undefined' || skip38.indexOf('frame') === -1)
-            elms[38].set('frame', component.maxFps[1])
+            if (elms[38] !== undefined) elms[38].set('frame', component.maxFps[1])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[39][Symbol.for('props')]['frame'] = component.maxFps[1]
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           if (typeof skip40 === 'undefined' || skip40.indexOf('frame') === -1)
-            elms[40].set('frame', component.maxFps[2])
+            if (elms[40] !== undefined) elms[40].set('frame', component.maxFps[2])
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
           elms[41][Symbol.for('props')]['frame'] = component.maxFps[2]

package/src/components/RouterView.js

@@ -17,6 +17,7 @@
 
 import Component from '../component.js'
 import Router from '../router/router.js'
+import symbols from '../lib/symbols.js'
 
 let hashchangeHandler = null
 
@@ -58,7 +59,10 @@ export default () =>
       }
     },
     hooks: {
-      ready() {
+      async ready() {
+        if (this.parent[symbols.routerHooks] && this.parent[symbols.routerHooks].init) {
+          await this.parent[symbols.routerHooks].init.apply(this.parent)
+        }
         hashchangeHandler = () => Router.navigate.apply(this)
         Router.navigate.apply(this)
         window.addEventListener('hashchange', hashchangeHandler)

package/src/components/Sprite.js

@@ -52,10 +52,10 @@ export default () =>
       },
       effects: [
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('texture', component.texture)
+          if (elms[0] !== undefined) elms[0].set('texture', component.texture)
         },
         function anonymous(component, elms, context, components, rootComponent, effect) {
-          elms[0].set('color', component.color)
+          if (elms[0] !== undefined) elms[0].set('color', component.color)
         },
       ],
       context: {},

package/src/engines/L3/element.js

@@ -22,9 +22,6 @@ import { Log } from '../../lib/log.js'
 import symbols from '../../lib/symbols.js'
 import Settings from '../../settings.js'
 
-// temporary counter to work around shader caching issues
-let counter = 0
-
 /**
  * Creates a padding object from a value and direction.
  * @param {number|object|string|undefined} padding - The padding value.
@@ -90,10 +87,11 @@ const layoutFn = function (config) {
 
   const children = this.node.children
   const childrenLength = children.length
+  const elementChildren = this.children
   let otherDimension = 0
   const gap = config.gap || 0
   for (let i = 0; i < childrenLength; i++) {
-    if (this.children[i] !== undefined && this.children[i].props.raw.show === false) {
+    if (elementChildren[i] !== undefined && elementChildren[i].props.raw.show === false) {
       continue
     }
     const node = children[i]
@@ -548,6 +546,7 @@ const Element = {
    */
   set(prop, value) {
     if (value === undefined) return
+    if (this.props === undefined) return
     // @ts-ignore
     if (this.props.raw[prop] === value) return
     // @ts-ignore
@@ -686,9 +685,6 @@ const Element = {
     this.config = null
     delete this.config
 
-    this.counter = null
-    delete this.counter
-
     this.props.raw = {}
     this.props.element = null
     this.props.props = null
@@ -714,9 +710,20 @@ const Element = {
     return this.node && this.node.parent
   },
   get children() {
-    return this.component[symbols.getChildren]().filter((child) => {
-      return child.parent === (this[symbols.isSlot] ? this.node.children[0] : this.node)
-    })
+    const allChildren = this.component[symbols.getChildren]()
+    const directChildren = []
+    const l = allChildren.length
+    for (let i = 0; i < l; i++) {
+      const child = allChildren[i]
+      if (
+        child !== undefined &&
+        child.parent === (this[symbols.isSlot] ? this.node.children[0] : this.node)
+      ) {
+        directChildren.push(child)
+      }
+    }
+
+    return directChildren
   },
 }
 
@@ -739,6 +746,5 @@ export default (config, component) => {
     scheduledTransitions: {},
     config,
     component,
-    counter: counter++,
   })
 }

package/src/focus.js

@@ -48,7 +48,10 @@ export default {
           focusedComponent = component
           focusedComponent.lifecycle.state = 'focus'
           if (event instanceof KeyboardEvent) {
-            document.dispatchEvent(new KeyboardEvent('keydown', event))
+            const internalEvent = new KeyboardEvent('keydown', event)
+            // @ts-ignore - this is an internal event
+            internalEvent[symbols.internalEvent] = true
+            document.dispatchEvent(internalEvent)
           } else {
             focusChain = []
           }

package/src/lib/codegenerator/generator.js

@@ -162,11 +162,14 @@ const generateElementCode = function (
         this.effectsCode.push(`
         if(typeof skip${counter} === 'undefined' ||
           skip${counter}.indexOf('${key.substring(1)}') === -1)
-          ${elm}.set('${key.substring(1)}', ${interpolate(templateObject[key], options.component)})
+          if(${elm} !== undefined) ${elm}.set('${key.substring(1)}', ${interpolate(
+          templateObject[key],
+          options.component
+        )})
         `)
       } else {
         this.effectsCode.push(`
-            ${elm}.set('${key.substring(1)}', ${interpolate(
+            if(${elm} !== undefined) ${elm}.set('${key.substring(1)}', ${interpolate(
           templateObject[key],
           options.component
         )})

package/src/lib/symbols.js

@@ -13,6 +13,7 @@
  * @property {symbol} index
  * @property {symbol} init
  * @property {symbol} inputEvents
+ * @property {symbol} internalEvent
  * @property {symbol} intervals
  * @property {symbol} launched
  * @property {symbol} level
@@ -62,6 +63,7 @@ export default {
   index: Symbol('index'),
   init: Symbol('init'),
   inputEvents: Symbol('inputEvents'),
+  internalEvent: Symbol('internalEvent'),
   intervals: Symbol('intervals'),
   launched: Symbol('launched'),
   level: Symbol('level'),

package/src/router/router.js

@@ -207,18 +207,29 @@ export const navigate = async function () {
     const { hash, path, queryParams } = getHash()
     let route = matchHash(path, this.parent[symbols.routes])
 
-    // Adding the location hash to the route if it exists.
-    if (hash !== null) {
-      route.hash = hash
+    const queryParamsData = {}
+    const queryParamsEntries = [...queryParams.entries()]
+    for (let i = 0; i < queryParamsEntries.length; i++) {
+      queryParamsData[queryParamsEntries[i][0]] = queryParamsEntries[i][1]
+    }
+
+    route.data = {
+      ...navigationData,
+      ...route.data,
+      ...queryParamsData,
     }
 
     currentRoute = route
     if (route) {
+      // Adding the location hash to the route if it exists.
+      if (hash !== null) {
+        route.hash = hash
+      }
       let beforeEachResult
       if (this.parent[symbols.routerHooks]) {
         const hooks = this.parent[symbols.routerHooks]
         if (hooks.beforeEach) {
-          beforeEachResult = await hooks.beforeEach(route, previousRoute)
+          beforeEachResult = await hooks.beforeEach.call(this.parent, route, previousRoute)
           if (isString(beforeEachResult)) {
             to(beforeEachResult)
             return
@@ -258,7 +269,6 @@ export const navigate = async function () {
 
       /** @type {import('../engines/L3/element.js').BlitsElement} */
       let holder
-      let routeData
 
       let { view, focus } = cacheMap.get(route.hash) || {}
 
@@ -279,23 +289,11 @@ export const navigate = async function () {
         holder.set('w', '100%')
         holder.set('h', '100%')
 
-        const queryParamsData = {}
-        const queryParamsEntries = [...queryParams.entries()]
-        for (let i = 0; i < queryParamsEntries.length; i++) {
-          queryParamsData[queryParamsEntries[i][0]] = queryParamsEntries[i][1]
-        }
-
-        routeData = {
-          ...navigationData,
-          ...route.data,
-          ...queryParamsData,
-        }
-
         // merge props with potential route params, navigation data and route data to be injected into the component instance
         const props = {
           ...this[symbols.props],
           ...route.params,
-          ...routeData,
+          ...route.data,
         }
 
         view = await route.component({ props }, holder, this)
@@ -369,7 +367,7 @@ export const navigate = async function () {
       state.path = route.path
       state.params = route.params
       state.hash = hash
-      state.data = routeData
+      state.data = route.data
 
       // apply in transition
       if (route.transition.in) {
@@ -383,10 +381,14 @@ export const navigate = async function () {
           await setOrAnimate(holder, route.transition.in, shouldAnimate)
         }
       }
-
-      this.activeView = this[symbols.children][this[symbols.children].length - 1]
+      const children = this[symbols.children]
+      this.activeView = children[children.length - 1]
     } else {
       Log.error(`Route ${hash} not found`)
+      const routerHooks = this.parent[symbols.routerHooks]
+      if (routerHooks && typeof routerHooks.error === 'function') {
+        routerHooks.error.call(this.parent, `Route ${hash} not found`)
+      }
     }
   }