@lightningjs/blits 2.0.0-beta.1 → 2.0.0-beta.4

package/src/components/RouterView.js

@@ -16,141 +16,158 @@
  */
 
 import Component from '../component.js'
-import Router from '../router/router.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
 
+/** @typedef {{ $input?: (event: any) => boolean, $focus?: (event: any) => void }} RouterViewParent */
+
 export default () =>
-  Component('RouterView', {
-    /* eslint-disable no-unused-vars */
-    code: {
-      render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
-        const elms = []
-        const validAttributes = [
-          'parent',
-          'rotation',
-          'w',
-          'width',
-          'h',
-          'height',
-          'x',
-          'y',
-          'z',
-          'zIndex',
-          'color',
-          'src',
-          'texture',
-          'fit',
-          'rtt',
-          'mount',
-          'pivot',
-          'scale',
-          'show',
-          'alpha',
-          'rounded',
-          'border',
-          'shadow',
-          'shader',
-          'clipping',
-          'overflow',
-          'font',
-          'size',
-          'maxwidth',
-          'maxheight',
-          'maxlines',
-          'textoverflow',
-          'letterspacing',
-          'lineheight',
-          'contain',
-          'align',
-          'content',
-          'placement',
-          'inspector-data',
-        ]
-        const elementConfigs = []
-        const forloops = []
-        const props = []
-        const created = []
-        const effects = {}
-        const skips = []
-        let componentType
-        let rootComponent = component
-        let propData
-        let slotComponent
-        let inSlot = false
-        let slotChildCounter = 0
-        let cmps = []
-        elementConfigs[0] = {}
+  Component(
+    'RouterView',
+    /** @type {any} */ ({
+      /* eslint-disable no-unused-vars */
+      code: {
+        render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
+          const elms = []
+          const validAttributes = [
+            'parent',
+            'rotation',
+            'w',
+            'width',
+            'h',
+            'height',
+            'x',
+            'y',
+            'z',
+            'zIndex',
+            'color',
+            'src',
+            'texture',
+            'fit',
+            'rtt',
+            'mount',
+            'pivot',
+            'scale',
+            'show',
+            'alpha',
+            'rounded',
+            'border',
+            'shadow',
+            'shader',
+            'clipping',
+            'overflow',
+            'font',
+            'size',
+            'maxwidth',
+            'maxheight',
+            'maxlines',
+            'textoverflow',
+            'letterspacing',
+            'lineheight',
+            'contain',
+            'align',
+            'content',
+            'placement',
+            'inspector-data',
+            'holder',
+          ]
+          const elementConfigs = []
+          const forloops = []
+          const props = []
+          const created = []
+          const effects = {}
+          const skips = []
+          let componentType
+          let rootComponent = component
+          let propData
+          let slotComponent
+          let inSlot = false
+          let slotChildCounter = 0
+          let cmps = []
+          elementConfigs[0] = {}
+          elementConfigs[0]['___wrapper'] = true
 
-        elms[0] = this.element(
-          { parent: parent || 'root' },
-          inSlot === true ? slotComponent : component
-        )
+          elms[0] = this.element(
+            { parent: parent || 'root' },
+            inSlot === true ? slotComponent : component
+          )
 
-        elementConfigs[0]['w'] = parent.node.w * (100 / 100)
-        elementConfigs[0]['h'] = parent.node.h * (100 / 100)
-        elms[0].populate(elementConfigs[0])
+          elementConfigs[0]['w'] = parent.node.w * (100 / 100)
+          elementConfigs[0]['height'] = parent.node.h * (100 / 100)
+          elms[0].populate(elementConfigs[0])
 
-        if (inSlot === true) {
-          slotChildCounter -= 1
-        }
+          if (inSlot === true) {
+            slotChildCounter -= 1
+          }
 
-        return {
-          elms,
-          cleanup: () => {
-            rootComponent = null
-            propData = null
-            slotComponent = null
-            parent = null
-            component = null
-            cmps.length = 0
-            elms.length = 0
-            components.length = 0
-            elementConfigs.length = 0
-            forloops.length = 0
-            props.length = 0
-            skips.length = 0
-          },
-          skips,
-        }
+          return {
+            elms,
+            cleanup: () => {
+              rootComponent = null
+              propData = null
+              slotComponent = null
+              parent = null
+              component = null
+              cmps.length = 0
+              elms.length = 0
+              components.length = 0
+              elementConfigs.length = 0
+              forloops.length = 0
+              props.length = 0
+              skips.length = 0
+            },
+            skips,
+          }
+        },
+        effects: [],
+        context: {},
       },
-      effects: [],
-      context: {},
-    },
-    state() {
-      return {
-        activeView: null,
-      }
-    },
-    hooks: {
-      async ready() {
-        if (
-          this[symbols.parent][symbols.routerHooks] &&
-          this[symbols.parent][symbols.routerHooks].init
-        ) {
-          await this[symbols.parent][symbols.routerHooks].init.apply(this[symbols.parent])
+      state() {
+        return {
+          activeView: null,
         }
-        hashchangeHandler = () => Router.navigate.apply(this)
-        Router.navigate.apply(this)
-        window.addEventListener('hashchange', hashchangeHandler)
-      },
-      destroy() {
-        window.removeEventListener('hashchange', hashchangeHandler, false)
       },
-      focus() {
-        if (this.activeView && Focus.get() === this) {
-          this.activeView.$focus()
-        }
+      hooks: {
+        async ready() {
+          const parent = this[symbols.parent]
+          if (parent && parent[symbols.routerHooks] && parent[symbols.routerHooks].init) {
+            await parent[symbols.routerHooks].init.apply(parent)
+          }
+
+          hashchangeHandler = () => Router.navigate.apply(this)
+          Router.navigate.apply(this)
+          window.addEventListener('hashchange', hashchangeHandler)
+        },
+        destroy() {
+          window.removeEventListener('hashchange', hashchangeHandler, false)
+        },
+        focus() {
+          if (this.activeView && Focus.get() === this) {
+            this.activeView.$focus()
+          }
+        },
       },
-    },
-    input: {
-      back(e) {
-        const navigating = Router.back.call(this)
-        if (navigating === false) {
-          this[symbols.parent].$focus(e)
-        }
+      input: {
+        back(e) {
+          const parent = this[symbols.parent]
+
+          if (routerState.backNavigation === false) {
+            if (parent && parent.$input) {
+              parent.$input(e)
+            }
+            return
+          }
+
+          const navigating = Router.back.call(this)
+          if (navigating === false) {
+            if (parent && parent.$focus) {
+              parent.$focus(e)
+            }
+          }
+        },
       },
-    },
-  })
+    })
+  )

package/src/components/Sprite.js

@@ -65,6 +65,7 @@ export default () =>
           'content',
           'placement',
           'inspector-data',
+          'holder',
         ]
         const elementConfigs = []
         const forloops = []
@@ -80,6 +81,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },
@@ -90,7 +92,9 @@ export default () =>
         elementConfigs[0]['h'] = parent.node.h * (100 / 100)
         elementConfigs[0]['texture'] = component.texture
         elementConfigs[0]['color'] = component.color
-        elementConfigs[0]['effects'] = component.effects
+        elementConfigs[0]['rounded'] = component.rounded
+        elementConfigs[0]['border'] = component.border
+        elementConfigs[0]['shadow'] = component.shadow
         elms[0].populate(elementConfigs[0])
 
         if (inSlot === true) {
@@ -123,6 +127,15 @@ export default () =>
         function anonymous(component, elms, context, components, rootComponent, skips, effect) {
           elms[0].set('color', component.color)
         },
+        function anonymous(component, elms, context, components, rootComponent, skips, effect) {
+          elms[0].set('rounded', component.rounded)
+        },
+        function anonymous(component, elms, context, components, rootComponent, skips, effect) {
+          elms[0].set('border', component.border)
+        },
+        function anonymous(component, elms, context, components, rootComponent, skips, effect) {
+          elms[0].set('shadow', component.shadow)
+        },
       ],
       context: {},
     },
@@ -131,6 +144,9 @@ export default () =>
       map: undefined,
       frame: undefined,
       color: undefined,
+      rounded: undefined,
+      border: undefined,
+      shadow: undefined,
     },
     state() {
       return {
@@ -167,15 +183,20 @@ export default () =>
         // Resolve frame data from sprite map
         let options = null
         if (
-          this.map !== undefined &&
           this.map !== null &&
-          this.frame !== undefined &&
-          this.frame !== null
+          this.map !== undefined &&
+          this.frame !== null &&
+          this.frame !== undefined
         ) {
-          options =
-            'frames' in this.map
-              ? Object.assign({}, this.map.defaults || {}, this.map.frames[this.frame])
-              : this.map[this.frame]
+          if (
+            this.map.frames !== null &&
+            this.map.frames !== undefined &&
+            this.frame in this.map.frames
+          ) {
+            options = Object.assign({}, this.map.defaults || {}, this.map.frames[this.frame])
+          } else if (this.frame in this.map) {
+            options = this.map[this.frame]
+          }
         }
 
         // If no map but frame is object (manual subtexture)

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

@@ -24,6 +24,8 @@ import symbols from '../../lib/symbols.js'
 import Settings from '../../settings.js'
 import shaders from '../../lib/shaders/shaders.js'
 
+const holderComponentMap = new WeakMap()
+
 /**
  * Creates a padding object from a value and direction.
  * @param {number|object|string|undefined} padding - The padding value.
@@ -210,15 +212,29 @@ const propsTransformer = {
     this.props['rotation'] = v * (Math.PI / 180)
   },
   set w(v) {
-    if (v < 0) v = 0
-    this.props['w'] = parsePercentage.call(this, v, 'w')
+    const parsed = parsePercentage.call(this, v, 'w')
+    this.props['w'] = parsed
+    if (
+      this.___wrapper === true &&
+      this.element.component.eol !== true &&
+      this.element.component[symbols.holder] !== undefined
+    ) {
+      this.element.component[symbols.holder].set('w', parsed)
+    }
   },
   set width(v) {
     this.w = v
   },
   set h(v) {
-    if (v < 0) v = 0
-    this.props['h'] = parsePercentage.call(this, v, 'h')
+    const parsed = parsePercentage.call(this, v, 'h')
+    this.props['h'] = parsed
+    if (
+      this.___wrapper === true &&
+      this.element.component.eol !== true &&
+      this.element.component[symbols.holder] !== undefined
+    ) {
+      this.element.component[symbols.holder].set('h', parsed)
+    }
   },
   set height(v) {
     this.h = v
@@ -509,6 +525,9 @@ const propsTransformer = {
       this.props['data'] = v
     }
   },
+  set holder(v) {
+    this.props['interactive'] = v
+  },
 }
 
 export const elementAttributes = Object.keys(propsTransformer)
@@ -564,6 +583,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.w, h: dimensions.h, type }, this)
@@ -587,6 +610,39 @@ const Element = {
       })
     }
   },
+  /**
+   * Sets framework-provided inspector metadata
+   * Only sets if inspector is enabled and in dev mode
+   * @param {Object} data - Framework inspector metadata to merge
+   */
+  setInspectorMetadata(data) {
+    // Early return if inspector not enabled (performance optimization)
+    if (inspectorEnabled !== true) {
+      return
+    }
+
+    // Early return if element is destroyed (props.props is null)
+    if (this.props.props === undefined || this.props.props === null) {
+      return
+    }
+
+    // Initialize data object if it doesn't exist
+    if (this.props['data'] === undefined) {
+      this.props['data'] = {}
+    }
+    if (this.props.props['data'] === undefined) {
+      this.props.props['data'] = {}
+    }
+
+    // Merge framework data (blits-* keys data attributes)
+    Object.assign(this.props['data'], data)
+    Object.assign(this.props.props['data'], data)
+
+    // Sync to renderer node so inspector can see it
+    if (this.node !== undefined && this.node !== null) {
+      this.node.data = { ...this.props.props['data'] }
+    }
+  },
   /**
    * Set an individual property on the node
    *
@@ -632,13 +688,31 @@ const Element = {
     }
   },
   animate(prop, value, transition) {
+    // Clear any existing debounce timeout for this property
+    if (this.debounceTimeouts[prop] !== undefined) {
+      clearTimeout(this.debounceTimeouts[prop])
+      Log.debug(`Cleared debounce timeout for property "${prop}"`)
+    }
+
+    // Debounce the animation execution
+    this.debounceTimeouts[prop] = setTimeout(() => {
+      delete this.debounceTimeouts[prop]
+      this._executeAnimation(prop, value, transition)
+    }, 0)
+  },
+  _executeAnimation(prop, value, transition) {
     // check if a transition is already scheduled to run on the same prop
     // and cancels it if it does
+    const stateOfAnimation =
+      this.scheduledTransitions[prop] !== undefined
+        ? this.scheduledTransitions[prop].f.state
+        : undefined
+
     if (
-      this.scheduledTransitions[prop] !== undefined &&
-      this.scheduledTransitions[prop].f.state === 'scheduled'
+      stateOfAnimation !== undefined &&
+      (stateOfAnimation === 'scheduled' || stateOfAnimation === 'running')
     ) {
-      this.scheduledTransitions[prop].f.stop()
+      this.scheduledTransitions[prop].f.stop(stateOfAnimation === 'running' ? false : true)
     }
 
     // if current value is the same as the value to animate to, instantly resolve
@@ -674,6 +748,11 @@ const Element = {
       f,
     }
 
+    // Update inspector metadata when transition starts
+    if (inspectorEnabled === true) {
+      this.setInspectorMetadata({ 'blits-isTransitioning': true })
+    }
+
     if (transition.start !== undefined && typeof transition.start === 'function') {
       // fire transition start callback when animation really starts (depending on specified delay)
       f.once('animating', () => {
@@ -708,6 +787,12 @@ const Element = {
       }
       // remove the prop from scheduled transitions
       delete this.scheduledTransitions[prop]
+      // Update inspector metadata when transition ends
+      if (inspectorEnabled === true) {
+        this.setInspectorMetadata({
+          'blits-isTransitioning': Object.keys(this.scheduledTransitions).length > 0,
+        })
+      }
     })
 
     // start animation
@@ -717,6 +802,14 @@ const Element = {
     if (this.node === null) return
 
     Log.debug('Deleting Node', this.nodeId)
+
+    // Clear all pending debounce timeouts
+    const debounceProps = Object.keys(this.debounceTimeouts)
+    for (let i = 0; i < debounceProps.length; i++) {
+      clearTimeout(this.debounceTimeouts[debounceProps[i]])
+    }
+    this.debounceTimeouts = null
+
     // Clearing transition end callback functions
     const transitionProps = Object.keys(this.scheduledTransitions)
     for (let i = 0; i < transitionProps.length; i++) {
@@ -799,6 +892,7 @@ export default (config, component) => {
   return Object.assign(Object.create(Element), {
     props: Object.assign(Object.create(propsTransformer), { props: {} }),
     scheduledTransitions: {},
+    debounceTimeouts: {},
     config,
     component,
   })

package/src/engines/L3/launch.js

@@ -100,6 +100,7 @@ export default (App, target, settings = {}) => {
         textureMemory: textureMemorySettings(settings),
         createImageBitmapSupport: 'auto',
         targetFPS: 'maxFPS' in settings ? settings.maxFPS : 0,
+        platform: 'platform' in settings ? settings.platform : null,
       },
       ...(settings.advanced || {}),
     },
@@ -118,7 +119,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][symbols.parent] !== undefined) {
-    components.unshift(components[0][symbols.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,31 @@
+/*
+ * 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 symbols from '../lib/symbols.js'
+
+/**
+ * Recursive function that retrieves the ancestors of a component
+ * @param {Array} components
+ * @returns array components
+ */
+export const getAncestors = (components) => {
+  if (components[0][symbols.parent] !== undefined) {
+    components.unshift(components[0][symbols.parent])
+    return getAncestors(components)
+  }
+  return components
+}