@lightningjs/blits 1.49.0 → 1.51.0

package/src/components/RouterView.js

@@ -18,7 +18,7 @@
 import Component from '../component.js'
 import Router, { state as routerState } from '../router/router.js'
 import symbols from '../lib/symbols.js'
-import Focus from '../focus.js'
+import Focus from '../focus/focus.js'
 
 let hashchangeHandler = null
 

package/src/components/Sprite.js

@@ -85,8 +85,7 @@ export default () =>
       ],
       context: {},
     },
-    props: ['image', 'map', 'frame', 'color', 'effects'],
-
+    props: ['image', 'map', 'frame', 'color', 'effects', '@loaded', '@error'],
     state() {
       return {
         spriteTexture: null,
@@ -94,6 +93,33 @@ export default () =>
       }
     },
 
+    hooks: {
+      ready() {
+        const loaded = this['@loaded']
+        if (loaded && typeof loaded === 'function') {
+          const cb = (payload) => loaded({ w: payload?.w, h: payload?.h }, this[symbols.wrapper])
+          this._loadedCb = cb
+          if (this.spriteTexture !== undefined && this.spriteTexture !== null) {
+            this.spriteTexture.on('loaded', cb)
+          }
+        }
+        const error = this['@error']
+        if (error && typeof error === 'function') {
+          const cb = (payload) => error(payload, this[symbols.wrapper])
+          this._failedCb = cb
+          if (this.spriteTexture !== undefined && this.spriteTexture !== null) {
+            this.spriteTexture.on('failed', cb)
+          }
+        }
+      },
+      destroy() {
+        if (this.spriteTexture !== undefined && this.spriteTexture !== null) {
+          if (this._loadedCb) this.spriteTexture.off('loaded', this._loadedCb)
+          if (this._failedCb) this.spriteTexture.off('failed', this._failedCb)
+        }
+      },
+    },
+
     computed: {
       texture() {
         // If no image - nothing to render
@@ -113,10 +139,17 @@ export default () =>
           this.spriteTexture === null ||
           this.currentSrc !== this.image
         ) {
+          const prevTexture = this.spriteTexture
+          if (prevTexture !== undefined && prevTexture !== null) {
+            if (this._loadedCb) prevTexture.off('loaded', this._loadedCb)
+            if (this._failedCb) prevTexture.off('failed', this._failedCb)
+          }
           this.spriteTexture = renderer.createTexture('ImageTexture', {
             src: this.image,
           })
           this.currentSrc = this.image
+          if (this._loadedCb) this.spriteTexture.on('loaded', this._loadedCb)
+          if (this._failedCb) this.spriteTexture.on('failed', this._failedCb)
         }
 
         // Resolve frame data from sprite map

package/src/components/index.js

@@ -18,11 +18,9 @@
 import Circle from './Circle.js'
 import RouterView from './RouterView.js'
 import Sprite from './Sprite.js'
-import FPScounter from './FPScounter.js'
 
 export default () => ({
   Circle: Circle(),
   RouterView: RouterView(),
   Sprite: Sprite(),
-  FPScounter: FPScounter(),
 })

package/src/engines/L3/element.js

@@ -22,6 +22,8 @@ import { Log } from '../../lib/log.js'
 import symbols from '../../lib/symbols.js'
 import Settings from '../../settings.js'
 
+const holderComponentMap = new WeakMap()
+
 /**
  * Creates a padding object from a value and direction.
  * @param {number|object|string|undefined} padding - The padding value.
@@ -512,6 +514,9 @@ const propsTransformer = {
       this.props['data'] = v
     }
   },
+  set holder(v) {
+    this.props['interactive'] = v
+  },
 }
 
 const Element = {
@@ -555,6 +560,10 @@ const Element = {
       ? renderer.createTextNode({ ...textDefaults, ...this.props.props })
       : renderer.createNode(this.props.props)
 
+    if (this.props['holder'] === true) {
+      holderComponentMap.set(this.node, this.component)
+    }
+
     if (props['@loaded'] !== undefined && typeof props['@loaded'] === 'function') {
       this.node.on('loaded', (el, { type, dimensions }) => {
         props['@loaded']({ w: dimensions.width, h: dimensions.height, type }, this)

package/src/engines/L3/launch.js

@@ -118,7 +118,9 @@ export default (App, target, settings = {}) => {
 
   shaderLoader()
   fontLoader()
-  initApp()
+  // Defer app initialization until after the current call stack is cleared,
+  // allowing the renderer to finish setting up before the app starts creating components
+  Promise.resolve().then(initApp)
 
   return renderer
 }

package/src/{focus.js → focus/focus.js}

@@ -15,11 +15,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import symbols from './lib/symbols.js'
-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 symbols from '../lib/symbols.js'
+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'
 
 let focusedComponent = null
 let focusChain = []
@@ -99,19 +100,6 @@ export default {
   },
 }
 
-/**
- * Recursive function that retrieves the ancestors of a component
- * @param {Array} components
- * @returns array components
- */
-const getAncestors = (components) => {
-  if (components[0].parent !== undefined) {
-    components.unshift(components[0].parent)
-    return getAncestors(components)
-  }
-  return components
-}
-
 /**
  * Get the component in the ancestors chain that has a handler for a certain key code
  * @param {Object} component

package/src/focus/helpers.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 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
+ */
+
+/**
+ * Recursive function that retrieves the ancestors of a component
+ * @param {Array} components
+ * @returns array components
+ */
+export const getAncestors = (components) => {
+  if (components[0].parent !== undefined) {
+    components.unshift(components[0].parent)
+    return getAncestors(components)
+  }
+  return components
+}

package/src/focus/hover.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2025 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
+ */
+
+import { Log } from '../lib/log.js'
+import { getAncestors } from './helpers.js'
+
+let hoveredComponent = null
+let hoverChain = []
+
+export default {
+  get() {
+    return hoveredComponent
+  },
+  set(component) {
+    if (component === undefined || component.eol === true) return
+
+    // early return if already hovered
+    if (component === hoveredComponent) return
+
+    if (hoveredComponent === null) {
+      hoverChain = getAncestors([component])
+    }
+
+    // unhover currently hovered components
+    if (hoveredComponent !== null) {
+      if (hoverChain[hoverChain.length - 1] === component.parent) {
+        hoverChain.push(component)
+      } else {
+        const newhoverChain = getAncestors([component])
+        let i = hoverChain.length
+        while (i--) {
+          // don't unhover when part of the new hover chain
+          if (newhoverChain.indexOf(hoverChain[i]) > -1) break
+          // skip if component is destroyed
+          if (hoverChain[i].eol !== true) {
+            hoverChain[i].lifecycle.state = 'unhover'
+          }
+        }
+        hoverChain = newhoverChain
+      }
+    }
+
+    // ensure that all components in the hover path have hover state
+    let i = 0
+    while (i < hoverChain.length - 1) {
+      // skip if component is destroyed
+      if (hoverChain[i].eol !== true) {
+        hoverChain[i].lifecycle.state = 'hover'
+      }
+      i++
+    }
+
+    setHover(component)
+  },
+  clear() {
+    if (hoveredComponent === null) return
+    for (let i = 0; i < hoverChain.length; i++) {
+      if (hoverChain[i].eol !== true) {
+        hoverChain[i].lifecycle.state = 'unhover'
+      }
+    }
+    hoveredComponent = null
+    hoverChain = []
+  },
+}
+
+/**
+ * Set the hover to the Component
+ * @param {Object} component  - The component to hover
+ */
+const setHover = (component) => {
+  Log.info(
+    '\nHover chain:\n',
+    hoverChain.map((c, index) => '\t'.repeat(index) + '↳ ' + c.componentId).join('\n')
+  )
+
+  hoveredComponent = component
+  component.lifecycle.state = 'hover'
+}

package/src/launch.js

@@ -89,6 +89,7 @@ async function rendererVersion() {
  * @property {number} [textureProcessingTimeLimit] - Max time renderer can process textures in a frame
  * @property {Partial<import('@lightningjs/renderer').RendererMainSettings>} [advanced] - Advanced renderer settings
  * @property {boolean} [announcer] - Whether or not the announcer should be activated on initialization
+ * @property {boolean} [enableMouse] - Enable mouse support (hover and click-to-focus). Defaults to false.
  * @property {number} [maxFPS] - Maximum FPS
  */
 

package/src/lib/codegenerator/generator.js

@@ -174,6 +174,10 @@ const generateElementCode = function (
     renderCode.push(`elementConfigs[${counter}][Symbol.for('isSlot')] = true`)
   }
 
+  if (options.holder) {
+    renderCode.push(`elementConfigs[${counter}]['holder'] = true`)
+  }
+
   Object.keys(templateObject).forEach((key) => {
     if (key === 'slot') {
       renderCode.push(`

package/src/lib/lifecycle.js

@@ -31,6 +31,8 @@ const states = [
   'ready', // fired when component instantiated, reactivity setup done and template spawned
   'focus', // fired when receiving focus (can occur multiple times)
   'unfocus', // fired when losing focus (can occur multiple times)
+  'hover', // fired when receiving focus (can occur multiple times)
+  'unhover', // fired when losing focus (can occur multiple times)
   'destroy', // fired when component is destroyed and removed
   'attach', // fired when entering the viewport margin and attached to the render tree
   'detach', // fired when leaving the viewport margin and detached from the render tree
@@ -85,11 +87,16 @@ export default {
       // emit 'public' hook
       emit(v, this.component[symbols.identifier], this.component)
       // update the built-in hasFocus state variable
+      if (v === 'focus') this.component[symbols.state].hasFocus = true
+      if (v === 'unfocus') this.component[symbols.state].hasFocus = false
       if (v === 'focus' || v === 'unfocus') {
         if (inspectorEnabled === null) {
           inspectorEnabled = Settings.get('inspector', false)
         }
       }
+      // update the built-in isHovered state variable
+      if (v === 'hover') this.component[symbols.state].isHovered = true
+      if (v === 'unhover') this.component[symbols.state].isHovered = false
       if (v === 'focus') {
         this.component[symbols.state].hasFocus = true
         if (

package/src/router/router.js

@@ -21,7 +21,7 @@ import { reactive } from '../lib/reactivity/reactive.js'
 import symbols from '../lib/symbols.js'
 import { Log } from '../lib/log.js'
 import { stage } from '../launch.js'
-import Focus from '../focus.js'
+import Focus from '../focus/focus.js'
 import Announcer from '../announcer/announcer.js'
 import Settings from '../settings.js'
 
@@ -216,12 +216,17 @@ const defaultOptions = {
 }
 
 const makeRouteObject = (route, overrides) => {
+  // FIX: exclude keepAlive from the destination route options. Unlike other
+  // overrides, keepAlive applies to the route being LEFT, not the destination.
+  // It is consumed by removeView() instead.
+  const { keepAlive: _keepAlive, ...destOverrides } = overrideOptions // eslint-disable-line no-unused-vars
+
   const cleanRoute = {
     hash: overrides.hash,
     path: route.path,
     component: route.component,
     transition: 'transition' in route ? route.transition : fadeInFadeOutTransition,
-    options: { ...defaultOptions, ...route.options, ...overrideOptions },
+    options: { ...defaultOptions, ...route.options, ...destOverrides },
     announce: route.announce || false,
     hooks: route.hooks || {},
     data: { ...route.data, ...navigationData, ...overrides.queryParams },
@@ -342,8 +347,12 @@ export const navigate = async function () {
 
       // add the previous route (technically still the current route at this point)
       // into the history stack when inHistory is true and we're not navigating back
+      //
+      // FIX: use truthy check instead of `!== undefined` because matchHash()
+      // can return `false`, which survives `!== undefined` but has no `.options`.
       if (
-        previousRoute !== undefined &&
+        previousRoute &&
+        previousRoute.options &&
         previousRoute.options.inHistory === true &&
         navigatingBack === false
       ) {
@@ -485,7 +494,8 @@ export const navigate = async function () {
 
       // apply out out transition on previous view if available, unless
       // we're reusing the prvious page component
-      if (previousRoute !== undefined && reuse === false) {
+      // FIX: truthy guard — previousRoute can be `false` (see history-push comment above).
+      if (previousRoute && reuse === false) {
         // only animate when there is a previous route
         shouldAnimate = true
         const oldView = this[symbols.children].splice(1, 1).pop()
@@ -542,6 +552,12 @@ export const navigate = async function () {
     }
   }
 
+  // Clear module-level variables after removeView has consumed them.
+  // Placed here so it executes for all navigation flows, not only when
+  // previousRoute exists and reuse is false.
+  overrideOptions = {}
+  navigationData = {}
+
   // reset navigating indicators
   navigatingBack = false
   state.navigating = false
@@ -569,11 +585,18 @@ const removeView = async (route, view, transition, navigatingBack) => {
     }
   }
 
+  // Resolve effective keepAlive: runtime override from $router.to() takes precedence
+  // over the static route config option
+  const keepAlive =
+    overrideOptions.keepAlive !== undefined
+      ? overrideOptions.keepAlive
+      : route.options && route.options.keepAlive
+
   // cache the page when it's as 'keepAlive' instead of destroying
   if (
     navigatingBack === false &&
     route.options &&
-    route.options.keepAlive === true &&
+    keepAlive === true &&
     route.options.inHistory === true
   ) {
     const historyItem = history[history.length - 1]
@@ -588,7 +611,7 @@ const removeView = async (route, view, transition, navigatingBack) => {
    * 2. Navigating back, and the previous route is configured with "keep alive" set to true.
    * 3. Navigating back, and the previous route is not configured with "keep alive" set to true.
    */
-  if (route.options && (route.options.keepAlive !== true || navigatingBack === true)) {
+  if (route.options && (keepAlive !== true || navigatingBack === true)) {
     view.destroy()
     view = null
   }