@lightningjs/blits 2.4.1 → 2.6.0

package/src/plugins/storage/localCookie.js

@@ -15,6 +15,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { platform } from '../../platform.js'
+
 // LocalStorage and Cookie storage library
 class localCookie {
   constructor(options) {
@@ -41,7 +43,8 @@ class localCookie {
 
   // Checks if local storage is available and works
   _checkIfLocalStorageWorks() {
-    if (typeof localStorage !== 'undefined') {
+    const localStorage = platform.localStorage
+    if (localStorage !== undefined) {
       try {
         localStorage.setItem('feature_test', 'yes')
         if (localStorage.getItem('feature_test') === 'yes') {
@@ -66,23 +69,23 @@ class localCookie {
    * Local Storage APIs
    */
   _getItemLocalStorage(key) {
-    return window.localStorage.getItem(key)
+    return platform.localStorage.getItem(key)
   }
 
   _setItemLocalStorage(key, value) {
-    return window.localStorage.setItem(key, value)
+    return platform.localStorage.setItem(key, value)
   }
 
   _removeItemLocalStorage(key) {
-    return window.localStorage.removeItem(key)
+    return platform.localStorage.removeItem(key)
   }
 
   _clearLocalStorage() {
-    return window.localStorage.clear()
+    return platform.localStorage.clear()
   }
 
   _getLocalStorageKeys() {
-    return Object.keys(window.localStorage)
+    return Object.keys(platform.localStorage)
   }
 
   /*
@@ -91,7 +94,7 @@ class localCookie {
   _getItemCookie(key) {
     /* eslint-disable */
 		function escape(s) { return s.replace(/([.*+?\^${}()|\[\]\/\\])/g, '\\$1'); };
-		var match = document.cookie.match(RegExp('(?:^|;\\s*)' + escape(key) + '=([^;]*)'));
+		var match = platform.getCookie().match(RegExp('(?:^|;\\s*)' + escape(key) + '=([^;]*)'));
 
 		//if value in key of the entire cookie is empty, its deleted
 		if (match && match[1] === '')
@@ -103,13 +106,13 @@ class localCookie {
 	_setItemCookie(key, value) {
 		var now = new Date()
 		var expires = new Date(now.getTime() +1000*60*60*24*365*5) // 5 years!
-		document.cookie = `${key}=${value}; expires=${expires.toUTCString()};`
+		platform.setCookie(`${key}=${value}; expires=${expires.toUTCString()};`)
 		return //return undefined just like localStorage
 	}
 
 	_removeItemCookie(key) {
 		// to delete an k/v set the key to empty
-		document.cookie = `${key}=;Max-Age=-99999999;`
+		platform.setCookie(`${key}=;Max-Age=-99999999;`)
 		return //return undefined just like localStorage
 	}
 
@@ -117,14 +120,14 @@ class localCookie {
 		// empty all key/values in cookies
 		// 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");
+		platform.getCookie().split(";").forEach( (c) => {
+			platform.setCookie(c.replace(/^ +/, "").replace(/=.*/, "=;expires=;Max-Age=-99999999"));
 		});
 
 		return //return undefined
 	}
 	_getCookieKeys() {
-		return document.cookie.split(";").map((item)=>item.trim().split("=")[0])
+		return platform.getCookie().split(";").map((item)=>item.trim().split("=")[0])
 	}
 }
 

package/src/router/router.js

@@ -24,6 +24,7 @@ import { stage } from '../launch.js'
 import Focus from '../focus/focus.js'
 import Announcer from '../announcer/announcer.js'
 import Settings from '../settings.js'
+import { platform } from '../platform.js'
 
 /**
  * @typedef {import('../component.js').BlitsComponentFactory} BlitsComponentFactory - The component of the route
@@ -417,7 +418,8 @@ const executeBeforeHook = async function (
       this.currentRoute = previousRoute
       if (this.history.length > 0) {
         preventHashChangeNavigation = true
-        window.history.back()
+        platform.historyBack()
+
         navigatingBack = false
         state.navigating = false
       }
@@ -434,7 +436,7 @@ const executeBeforeHook = async function (
       this.currentRoute = previousRoute
       if (this.history.length > 0) {
         preventHashChangeNavigation = true
-        window.history.back()
+        platform.historyBack()
         navigatingBack = false
         state.navigating = false
       }

package/src/testing/index.d.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026 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 type { ComponentFactory, Settings } from '@lightningjs/blits'
+
+export interface SnapshotNode {
+  type: string
+  attributes: Record<string, any>
+  children: Array<SnapshotNode | ComponentSnapshotNode>
+}
+
+export interface ComponentSnapshotNode {
+  type: 'Component'
+  name: string
+  hasFocus: boolean
+  isHovered: boolean
+  attributes: Record<string, any>
+  props: Record<string, any>
+  state: Record<string, any>
+  tree: SnapshotNode | null
+}
+
+export interface RenderComponentOptions {
+  props?: Record<string, any>
+  settings?: Settings
+}
+
+export interface RenderComponentFixture {
+  component: any
+  root: any
+  snapshot(): SnapshotNode | ComponentSnapshotNode
+  setProps(props: Record<string, any>): void
+  setState(state: Record<string, any>): void
+  focus(event?: KeyboardEvent): Promise<any>
+  unfocus(): any
+  createKeyboardEvent(key: string, init?: KeyboardEventInit): KeyboardEvent
+  input(key: string, event?: KeyboardEvent): boolean
+  destroy(): void
+}
+
+export function renderComponent(
+  Component: ComponentFactory,
+  options?: RenderComponentOptions
+): RenderComponentFixture

package/src/testing/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026 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 renderComponent from './renderComponent.js'
+
+export { renderComponent }

package/src/testing/nodePlatform.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2026 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
+ */
+
+class TestKeyboardEvent {
+  constructor(type, init = {}) {
+    this.type = type
+    this.key = init.key
+    this.code = init.code
+    this.keyCode = init.keyCode || 0
+    this.bubbles = init.bubbles === true
+    this.cancelable = init.cancelable === true
+    this.composed = init.composed === true
+    this.timeStamp = init.timeStamp || Date.now()
+  }
+}
+
+const createEventTarget = () => {
+  const listeners = {}
+
+  return {
+    addEventListener(type, handler) {
+      listeners[type] = listeners[type] || []
+      listeners[type].push(handler)
+    },
+    removeEventListener(type, handler) {
+      const handlers = listeners[type]
+      if (handlers === undefined) return
+      const index = handlers.indexOf(handler)
+      if (index > -1) handlers.splice(index, 1)
+    },
+    dispatchEvent(event) {
+      const handlers = listeners[event.type] || []
+      for (let i = 0; i < handlers.length; i++) {
+        handlers[i](event)
+      }
+      return true
+    },
+  }
+}
+
+const createStorage = () => {
+  const store = {}
+
+  return {
+    getItem(key) {
+      return store[key] !== undefined ? store[key] : null
+    },
+    setItem(key, value) {
+      store[key] = String(value)
+    },
+    removeItem(key) {
+      delete store[key]
+    },
+    clear() {
+      const keys = Object.keys(store)
+      for (let i = 0; i < keys.length; i++) {
+        delete store[keys[i]]
+      }
+    },
+  }
+}
+
+const nodePlatform = () => {
+  const input = createEventTarget()
+  const viewport = createEventTarget()
+  let cookie = ''
+
+  return {
+    input,
+    viewport,
+    dispatchEvent: input.dispatchEvent.bind(input),
+    localStorage: createStorage(),
+    getCookie: () => cookie,
+    setCookie: (value) => {
+      cookie = value
+    },
+    historyBack() {},
+    screenHeight: 1080,
+    hardwareConcurrency: 1,
+    userAgent: 'node',
+    KeyboardEvent: TestKeyboardEvent,
+    isKeyboardEvent: (event) => event instanceof TestKeyboardEvent,
+    createKeyboardEvent: (type, init = {}) => new TestKeyboardEvent(type, init),
+    SpeechSynthesisUtterance: class TestSpeechSynthesisUtterance {
+      constructor(text = '') {
+        this.text = text
+      }
+    },
+    speechSynthesis: {
+      cancel() {},
+      getVoices() {
+        return []
+      },
+      pause() {},
+      resume() {},
+      speak() {},
+    },
+    now: Date.now,
+  }
+}
+
+export default nodePlatform

package/src/testing/renderComponent.js

@@ -0,0 +1,346 @@
+/*
+ * Copyright 2026 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 Settings from '../settings.js'
+import { renderer, stage } from '../launch.js'
+import symbols from '../lib/symbols.js'
+import { initLog } from '../lib/log.js'
+import { getRaw } from '../lib/reactivity/reactive.js'
+import Focus from '../focus/focus.js'
+import { initKeyMap, keyMap } from '../application.js'
+import { configurePlatform, platform } from '../platform.js'
+import nodePlatform from './nodePlatform.js'
+
+let nodeId = 0
+
+const renderComponent = (Component, options = {}) => {
+  const originalElement = stage.element
+  const originalPlatform = platform
+
+  Settings.set(options.settings || {})
+  configurePlatform(() => nodePlatform())
+  initLog()
+  initKeyMap()
+  mockRenderer()
+  // Generated template code calls stage.element through `this.element`
+  stage.element = createElement
+
+  const root = createElement()
+  const parent = {
+    $componentId: 'BlitsTestComponent::Root',
+    [symbols.lifecycle]: {
+      set state(v) {},
+    },
+    $focus() {},
+    $input() {
+      return false
+    },
+  }
+  const component = Component({ props: options.props || {} }, root, parent)
+
+  const snapshot = () => {
+    const holderMap = new WeakMap()
+    collectComponents(component, holderMap)
+    return componentSnapshot(component, holderMap)
+  }
+
+  const setProps = (props = {}) => {
+    const keys = Object.keys(props)
+    for (let i = 0; i < keys.length; i++) {
+      component[symbols.props][keys[i]] = props[keys[i]]
+    }
+  }
+
+  const setState = (state = {}) => {
+    const keys = Object.keys(state)
+    for (let i = 0; i < keys.length; i++) {
+      component[symbols.state][keys[i]] = state[keys[i]]
+    }
+  }
+
+  const focus = (event) => {
+    Focus.hold = false
+    component.$focus(event)
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        setTimeout(() => resolve(component))
+      })
+    })
+  }
+
+  const unfocus = () => {
+    component.unfocus()
+    return component
+  }
+
+  const input = (key, event = createKeyboardEvent(key)) => {
+    const focused = Focus.get()
+    if (focused === null || focused.eol === true || isInComponentTree(focused, component) === false)
+      return false
+    Focus.input(key, event)
+    return true
+  }
+
+  const destroy = () => {
+    if (component.eol !== true) {
+      component.destroy()
+    }
+    stage.element = originalElement
+    configurePlatform(() => originalPlatform)
+  }
+
+  return {
+    component,
+    root,
+    snapshot,
+    setProps,
+    setState,
+    focus,
+    unfocus,
+    createKeyboardEvent,
+    input,
+    destroy,
+  }
+}
+
+const mockRenderer = () => {
+  // Lifecycle hooks register renderer events even in headless tests
+  if (renderer.on === undefined) renderer.on = () => {}
+  if (renderer.off === undefined) renderer.off = () => {}
+}
+
+const collectComponents = (component, holderMap) => {
+  if (component === undefined || component === null) return
+  // Component tags render as holder elements; keep the link for snapshots
+  if (component[symbols.holder] !== undefined) {
+    holderMap.set(component[symbols.holder], component)
+  }
+  const children = component[symbols.children] || []
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]
+    if (child && child.$componentId !== undefined) {
+      collectComponents(child, holderMap)
+    }
+  }
+}
+
+const elementSnapshot = (element, holderMap) => {
+  const component = holderMap.get(element)
+  if (component !== undefined) {
+    return componentSnapshot(component, holderMap)
+  }
+
+  const children = []
+  for (let i = 0; i < element.children.length; i++) {
+    children.push(elementSnapshot(element.children[i], holderMap))
+  }
+
+  return {
+    type: elementType(element.attributes),
+    attributes: attributesSnapshot(element.attributes),
+    children,
+  }
+}
+
+const componentSnapshot = (component, holderMap) => {
+  const holder = component[symbols.holder]
+  const wrapper = component[symbols.wrapper]
+
+  return {
+    type: 'Component',
+    name: componentName(component),
+    hasFocus: component.$hasFocus === true,
+    isHovered: component.$isHovered === true,
+    attributes: holder ? attributesSnapshot(holder.attributes) : {},
+    props: propsSnapshot(component),
+    state: stateSnapshot(component),
+    tree: wrapper ? elementSnapshot(wrapper, holderMap) : null,
+  }
+}
+
+const attributesSnapshot = (attributes) => {
+  const out = {}
+  const keys = Object.keys(attributes)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (
+      key === '___wrapper' ||
+      key === '__textnode' ||
+      key === '__layout' ||
+      key === 'holder' ||
+      key === 'parent'
+    ) {
+      continue
+    }
+    if (attributes[key] !== undefined) {
+      out[key] = clone(attributes[key])
+    }
+  }
+  return out
+}
+
+const propsSnapshot = (component) => {
+  const props = component[symbols.props] || {}
+  const propKeys = component[symbols.propKeys] || Object.keys(props)
+  const out = {}
+  for (let i = 0; i < propKeys.length; i++) {
+    const key = propKeys[i]
+    if (props[key] !== undefined) {
+      out[key] = clone(props[key])
+    }
+  }
+  return out
+}
+
+const stateSnapshot = (component) => {
+  const state = component[symbols.state] || {}
+  const originalState = component[symbols.originalState] || {}
+  const stateKeys = Object.keys(originalState)
+  const out = {}
+  for (let i = 0; i < stateKeys.length; i++) {
+    const key = stateKeys[i]
+    if (key === '$hasFocus' || key === '$isHovered') continue
+    if (state[key] !== undefined) {
+      out[key] = clone(state[key])
+    }
+  }
+  return out
+}
+
+const componentName = (component) => {
+  const match = component.$componentId && component.$componentId.match(/^BlitsComponent::(.+)_\d+$/)
+  return match ? match[1] : 'Component'
+}
+
+const elementType = (attributes) => {
+  if (attributes.__textnode === true) return 'Text'
+  if (attributes.__layout === true) return 'Layout'
+  if (attributes[symbols.isSlot] === true) return 'Slot'
+  if (attributes[symbols.isSprite] === true) return 'Sprite'
+  return 'Element'
+}
+
+const clone = (value) => {
+  value = getRaw(value)
+
+  if (Array.isArray(value) === true) {
+    return value.map((v) => clone(v))
+  }
+
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return cleanObject(value)
+  }
+
+  return value
+}
+
+const cleanObject = (value) => {
+  const out = {}
+  const keys = Object.keys(value)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    if (value[key] !== undefined) {
+      out[key] = clone(value[key])
+    }
+  }
+  return out
+}
+
+const createElement = ({ parent } = {}) => {
+  // Minimal BlitsElement mock used by generated render/effect code
+  const element = {
+    attributes: {},
+    children: [],
+    node: {
+      children: [],
+      on() {},
+      off() {},
+    },
+    parent,
+    populate(attributes = {}) {
+      this.nodeId = ++nodeId
+      const keys = Object.keys(attributes)
+      for (let i = 0; i < keys.length; i++) {
+        this.set(keys[i], attributes[keys[i]])
+      }
+      if (attributes[symbols.isSlot] !== undefined) {
+        this.attributes[symbols.isSlot] = attributes[symbols.isSlot]
+      }
+      if (attributes[symbols.isSprite] !== undefined) {
+        this.attributes[symbols.isSprite] = attributes[symbols.isSprite]
+      }
+    },
+    set(key, value) {
+      this.attributes[key] = value
+      this.node[key] = value
+    },
+    setInspectorMetadata() {},
+    destroy() {
+      this.eol = true
+      this.children.length = 0
+      this.node.children.length = 0
+    },
+  }
+
+  appendToParent(element, parent)
+
+  return element
+}
+
+const appendToParent = (element, parent) => {
+  if (parent === undefined || parent === null || parent === 'root') return
+  if (parent.children === undefined) return
+  parent.children.push(element)
+  if (parent.node && parent.node.children) {
+    parent.node.children.push(element.node)
+  }
+}
+
+const createKeyboardEvent = (key, init = {}) => {
+  const keyCode = init.keyCode || keyCodeFromKey(key)
+  return platform.createKeyboardEvent('keydown', {
+    key,
+    ...init,
+    keyCode,
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+  })
+}
+
+const keyCodeFromKey = (key) => {
+  const keys = Object.keys(keyMap)
+  for (let i = 0; i < keys.length; i++) {
+    if (keyMap[keys[i]] === key) return Number(keys[i])
+  }
+  return 0
+}
+
+const isInComponentTree = (child, parent) => {
+  let current = child
+  while (current !== undefined && current !== null) {
+    if (current === parent) return true
+    current = current[symbols.parent]
+  }
+  return false
+}
+
+export default renderComponent