@lightningjs/blits 1.34.0 → 1.35.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+_22 Jul 2025_
+
+## v1.35.0
+
+- Added `byReference` param to `this.$emit()` to allow passing data without passing it by reference
+- Refactored focus handling
+  - more performant
+  - more robust for reassigning focus programatically (i.e. without direct key handling)
+  - fixed some cases where `$hasFocus` flag wasn't reset upon unfocus
+  - add logging of active focus chain upon focus changes
+- Improved overall test coverage to almost 80% (Blits Element, Focus, Theme plugin, Storage plugin)
+
 _10 Jul 2025_
 
 ## v1.34.0

package/index.d.ts

@@ -262,8 +262,12 @@ declare module '@lightningjs/blits' {
      * Emit events that other components can listen to
      * @param name - name of the event to be emitted
      * @param data - optional data to be passed along
+     * @param byReference - whether or not to pass the data by reference.
+     * The default behaviour is passing the data object by reference (`true`).
+     * When explicitely passing `false` the object will be recursively cloned
+     * and cleaned from any potential reactivity before emitting
      */
-    $emit(name: string, data?: any): void;
+    $emit(name: string, data?: any, byReference?: boolean): void;
 
     /**
     * Set a timeout that is automatically cleaned upon component destroy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -45,6 +45,7 @@
     "jsdom": "24.0.0",
     "lint-staged": "^15.5.0",
     "prettier": "^2.5.1",
+    "sinon": "^21.0.0",
     "tap-diff": "^0.1.1",
     "tape": "^5.5.0"
   },

package/src/component/base/events.js

@@ -23,12 +23,16 @@ export default {
    *
    * @param {string} event - The name of the event to emit.
    * @param {any} params - The parameters to pass to the event listeners.
+   * @param byReference - whether or not to pass the data by reference.
+   * The default behaviour is passing the data object by reference (`true`).
+   * When explicitely passing `false` the object will be recursively cloned
+   * and cleaned from any potential reactivity before emitting
    * @returns {boolean} True if all listeners executed, false otherwise.
    */
   $emit: {
-    value: function (event, params) {
+    value: function (event, params, byReference = true) {
       // returning if all listeners executed
-      return eventListeners.executeListeners(event, params)
+      return eventListeners.executeListeners(event, params, byReference)
     },
     writable: false,
     enumerable: true,

package/src/component/base/methods.js

@@ -40,8 +40,6 @@ export default {
      * @this {import('../../component').BlitsComponent}
      */
     value: function (e) {
-      if (this.eol === true) return
-      this[symbols.state].hasFocus = true
       Focus.set(this, e)
     },
     writable: false,

package/src/focus.js

@@ -19,6 +19,7 @@ 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'
 
 let focusedComponent = null
 let focusChain = []
@@ -38,56 +39,118 @@ export default {
     return focusedComponent
   },
   set(component, event) {
-    if (component === focusedComponent) return
     clearTimeout(setFocusTimeout)
-    focusedComponent && focusedComponent !== component.parent && focusedComponent.unfocus()
-    focusChain.reverse().forEach((cmp) => cmp.unfocus())
-    if (component !== focusedComponent) {
-      setFocusTimeout = setTimeout(
-        () => {
-          focusedComponent = component
-          focusedComponent.lifecycle.state = 'focus'
-          if (event instanceof KeyboardEvent) {
-            const internalEvent = new KeyboardEvent('keydown', event)
-            // @ts-ignore - this is an internal event
-            internalEvent[symbols.internalEvent] = true
-            document.dispatchEvent(internalEvent)
-          } else {
-            focusChain = []
-          }
-        },
-        this.hold ? Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS) : 0
-      )
+
+    // early return if already focused
+    if (component === focusedComponent) return
+
+    if (focusChain.length === 0) {
+      focusChain = getAncestors([component])
+    }
+
+    // unfocus currently focused components
+    if (focusedComponent !== null) {
+      if (focusChain[focusChain.length - 1] === component.parent) {
+        focusChain.push(component)
+      } else {
+        const newFocusChain = getAncestors([component])
+        let i = focusChain.length
+        while (i--) {
+          // don't unfocus when part of the new focus chain
+          if (newFocusChain.indexOf(focusChain[i]) > -1) break
+          focusChain[i].lifecycle.state = 'unfocus'
+        }
+        focusChain = newFocusChain
+      }
+    }
+
+    // ensure that all components in the focus path have focus state
+    let i = 0
+    while (i < focusChain.length - 1) {
+      focusChain[i].lifecycle.state = 'focus'
+      i++
+    }
+
+    // and finally set focus to the leaf component
+    if (this.hold === true) {
+      setFocusTimeout = setTimeout(() => {
+        setFocus(component, event)
+      }, Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS))
+    } else {
+      setFocus(component, event)
     }
   },
   input(key, event) {
     if (state.navigating === true) return
-    focusChain = walkChain([focusedComponent], key)
-    const componentWithInputEvent = focusChain.shift()
-
-    if (componentWithInputEvent) {
-      let cb
-      if (componentWithInputEvent[symbols.inputEvents][key]) {
-        cb = componentWithInputEvent[symbols.inputEvents][key].call(componentWithInputEvent, event)
-      } else if (componentWithInputEvent[symbols.inputEvents].any) {
-        cb = componentWithInputEvent[symbols.inputEvents].any.call(componentWithInputEvent, event)
-      }
-      if (cb !== undefined) {
-        keyUpCallbacks.set(event.code, cb)
-      }
+
+    const componentWithInputEvent = getComponentWithInputEvent(focusedComponent, key)
+
+    if (componentWithInputEvent === null) return
+
+    const inputEvents = componentWithInputEvent[symbols.inputEvents]
+
+    let cb
+    if (inputEvents[key]) {
+      cb = inputEvents[key].call(componentWithInputEvent, event)
+    } else if (inputEvents.any) {
+      cb = inputEvents.any.call(componentWithInputEvent, event)
+    }
+
+    if (cb !== undefined) {
+      keyUpCallbacks.set(event.code, cb)
     }
   },
 }
 
-const walkChain = (components, key) => {
+/**
+ * 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
+ * @param {String} key
+ * @returns component
+ */
+const getComponentWithInputEvent = (component, key) => {
   if (
-    components[0][symbols.inputEvents] &&
-    (typeof components[0][symbols.inputEvents][key] === 'function' ||
-      typeof components[0][symbols.inputEvents].any === 'function')
+    component[symbols.inputEvents] &&
+    (typeof component[symbols.inputEvents][key] === 'function' ||
+      typeof component[symbols.inputEvents].any === 'function')
   ) {
-    return components
-  } else if (components[0].parent) {
-    components.unshift(components[0].parent)
-    return walkChain(components, key)
-  } else return []
+    return component
+  } else if (component.parent !== undefined) {
+    return getComponentWithInputEvent(component.parent, key)
+  } else return null
+}
+
+/**
+ * Set the focus to the Component
+ * @param {Object} component  - The component fo focus
+ * @param {KeyboardEvent} event - Keyboard event
+ */
+const setFocus = (component, event) => {
+  Log.info(
+    '\nFocus chain:\n',
+    focusChain.map((c, index) => '\t'.repeat(index) + '↳ ' + c.componentId).join('\n')
+  )
+
+  focusedComponent = component
+  component.lifecycle.state = 'focus'
+
+  if (event instanceof KeyboardEvent) {
+    const internalEvent = new KeyboardEvent('keydown', event)
+    // @ts-ignore - this is an internal event
+    internalEvent[symbols.internalEvent] = true
+    document.dispatchEvent(internalEvent)
+  }
 }

package/src/lib/eventListeners.js

@@ -15,9 +15,30 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import symbols from './symbols.js'
+import { getRaw } from './reactivity/reactive.js'
+
 const eventsMap = new Map()
 const callbackCache = new Map()
 
+function isProxy(obj) {
+  return obj && typeof obj === 'object' && obj[symbols.isProxy] === true
+}
+
+function deepUnproxyClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj
+
+  const raw = isProxy(obj) ? getRaw(obj) : obj
+  const result = Array.isArray(raw) ? [] : {}
+
+  for (const key of Object.keys(raw)) {
+    const value = raw[key]
+    result[key] = value && typeof value === 'object' ? deepUnproxyClone(value) : value
+  }
+
+  return result
+}
+
 export default {
   /**
    * Registers a listener callback for a specific event on a component.
@@ -70,9 +91,16 @@ export default {
    *
    * @param {string} event - The name of the event to emit.
    * @param {any} params - The parameters to pass to the event listeners.
+   * @param byReference - whether or not to pass the data by reference.
+   * The default behaviour is passing the data object by reference (`true`).
+   * When explicitely passing `false` the object will be recursively cloned
+   * and cleaned from any potential reactivity before emitting
    * @returns {boolean} True if all listeners executed without stopping propagation, false if any listener returned false.
    */
-  executeListeners(event, params) {
+  executeListeners(event, params, byReference) {
+    if (byReference === false) {
+      params = deepUnproxyClone(params)
+    }
     const componentsMap = eventsMap.get(event)
     if (componentsMap === undefined || componentsMap.size === 0) {
       return true // No listeners, so execution can be considered successful

package/src/lib/lifecycle.js

@@ -70,12 +70,14 @@ export default {
    * @param {string} v - The new lifecycle state.
    */
   set state(v) {
-    if (states.indexOf(v) > -1 && (v !== this.current || v === 'focus')) {
+    if (states.indexOf(v) > -1 && v !== this.current) {
       Log.debug(
         `Setting lifecycle state from ${this.current} to ${v} for ${this.component.componentId}`
       )
       this.previous = this.current
       this.current = v
+      if (this.current === 'focus') this.component[symbols.state].hasFocus = true
+      if (this.current === 'unfocus') this.component[symbols.state].hasFocus = false
       // emit 'private' hook
       privateEmit(v, this.component[symbols.identifier], this.component)
       // emit 'public' hook

package/src/lib/reactivity/reactive.js

@@ -46,6 +46,10 @@ const reactiveProxy = (original, _parent = null, _key, global) => {
 
   const handler = {
     get(target, key, receiver) {
+      // return the original object instead of the proxied
+      if (key === symbols.isProxy) {
+        return true
+      }
       // return the original object instead of the proxied
       if (key === symbols.raw) {
         return original

package/src/lib/symbols.js

@@ -16,6 +16,7 @@
  * @property {symbol} inputEvents
  * @property {symbol} internalEvent
  * @property {symbol} intervals
+ * @property {symbol} isProxy
  * @property {symbol} launched
  * @property {symbol} level
  * @property {symbol} methodKeys
@@ -67,6 +68,7 @@ export default {
   inputEvents: Symbol('inputEvents'),
   internalEvent: Symbol('internalEvent'),
   intervals: Symbol('intervals'),
+  isProxy: Symbol('isProxy'),
   launched: Symbol('launched'),
   level: Symbol('level'),
   methodKeys: Symbol('methodKeys'),

package/src/plugins/storage/localCookie.js

@@ -120,14 +120,14 @@ class localCookie {
 		// What about cookies we got from the server? ¯\_(ツ)_/¯
 		// They should have the HttpOnly flag, so we shouldn't be able to delete them
 		document.cookie.split(";").forEach( (c) => {
-			document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=Max-Age=-99999999");
+			document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=;Max-Age=-99999999");
 		});
 
 		return //return undefined
 	}
 	_getCookieKeys() {
-		return document.cookie.split(";").map((item)=>item.split("=")[0])
+		return document.cookie.split(";").map((item)=>item.trim().split("=")[0])
 	}
 }
 
-export default localCookie
+export default localCookie

package/src/router/router.js

@@ -132,7 +132,7 @@ export const matchHash = (path, routes = []) => {
   let matchingRoute = false
   let i = 0
   while (!matchingRoute && i < routes.length) {
-    const route = { ...routes[i] }
+    const route = routes[i]
     route.path = normalizePath(route.path)
     if (route.path === path) {
       route.params = {}
@@ -206,20 +206,20 @@ export const navigate = async function () {
     let previousRoute = currentRoute //? Object.assign({}, currentRoute) : undefined
     const { hash, path, queryParams } = getHash()
     let route = matchHash(path, this.parent[symbols.routes])
-    const queryParamsData = {}
-    const queryParamsEntries = [...queryParams.entries()]
-    for (let i = 0; i < queryParamsEntries.length; i++) {
-      queryParamsData[queryParamsEntries[i][0]] = queryParamsEntries[i][1]
-    }
-
-    route.data = {
-      ...route.data,
-      ...navigationData,
-      ...queryParamsData,
-    }
 
     currentRoute = route
     if (route) {
+      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,
+      }
       // Adding the location hash to the route if it exists.
       if (hash !== null) {
         route.hash = hash