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

package/src/components/Sprite.js

@@ -80,6 +80,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },
@@ -167,15 +168,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/engines/L3/element.js

@@ -210,15 +210,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
@@ -587,6 +601,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 +679,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 +739,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 +778,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 +793,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 +883,7 @@ export default (config, component) => {
   return Object.assign(Object.create(Element), {
     props: Object.assign(Object.create(propsTransformer), { props: {} }),
     scheduledTransitions: {},
+    debounceTimeouts: {},
     config,
     component,
   })

package/src/lib/codegenerator/generator.js

@@ -163,6 +163,10 @@ const generateElementCode = function (
 
   renderCode.push(`elementConfigs[${counter}] = {}`)
 
+  if (counter === 0) {
+    renderCode.push(`elementConfigs[${counter}]['___wrapper'] = true `)
+  }
+
   if (options.forloop) {
     renderCode.push(`if(${elm} === undefined) {`)
   }
@@ -325,9 +329,11 @@ const generateComponentCode = function (
 
   const children = templateObject.children
   delete templateObject.children
+  // Capture holder counter before generating element code (which may process children and increment counter)
+  const holderCounter = counter
   generateElementCode.call(this, templateObject, parent, { ...options, ...{ holder: true } })
 
-  parent = options.key ? `elms[${counter}][${options.key}]` : `elms[${counter}]`
+  parent = options.key ? `elms[${holderCounter}][${options.key}]` : `elms[${holderCounter}]`
 
   counter++
 
@@ -396,6 +402,21 @@ const generateComponentCode = function (
     }
   `)
 
+  if (isDev === true) {
+    const templateTagName = templateObject[Symbol.for('componentType')]
+    const holderElm = options.key
+      ? `elms[${holderCounter}][${options.key}]`
+      : `elms[${holderCounter}]`
+    const componentDisplayName = `typeof componentType === 'string'
+      ? componentType
+      : (componentType?.[Symbol.for('componentType')] || '${templateTagName}')`
+    renderCode.push(`
+      if (${holderElm} !== undefined && typeof ${holderElm}.setInspectorMetadata === 'function') {
+        ${holderElm}.setInspectorMetadata({ 'blits-componentType': ${componentDisplayName} })
+      }
+    `)
+  }
+
   this.cleanupCode.push(`components[${counter}] = null`)
 
   if (options.forloop) {
@@ -451,7 +472,7 @@ const generateForLoopCode = function (templateObject, parent) {
     .replace(')', '')
     .split(/\s*,\s*/)
 
-  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)(\\$?\\w+))`, 'gi')
+  const scopeRegex = new RegExp(`(scope\\.(?!${item}\\.|${index}|key)([\\w$]+))`, 'gi')
 
   // local context
   const ctx = {
@@ -524,10 +545,16 @@ const generateForLoopCode = function (templateObject, parent) {
 
       component !== null && component[Symbol.for('removeGlobalEffects')](effects[${forStartCounter}])
 
-      for(let i = 0; i < effects[${forStartCounter}].length; i++) {
-        const value = effects[${forStartCounter}][i]
-        const index = component[Symbol.for('effects')].indexOf(value)
-        if (index > -1) component[Symbol.for('effects')].splice(index, 1)
+     const effectsToRemove = new Set(effects[${forStartCounter}].slice(0))
+      if (effectsToRemove.size > 0) {
+        const componentEffects = component?.[Symbol.for('effects')] || []
+        let writeIndex = 0
+        for (let readIndex = 0; readIndex < componentEffects.length; readIndex++) {
+          if (!effectsToRemove.has(componentEffects[readIndex])) {
+            componentEffects[writeIndex++] = componentEffects[readIndex]
+          }
+        }
+        componentEffects.length = writeIndex
       }
 
       effects[${forStartCounter}].length = 0
@@ -825,8 +852,13 @@ const cast = (val = '', key = false, component = 'component.') => {
   }
   // @-listener
   else if (key.startsWith('@') && val) {
-    const c = component.slice(0, -1)
-    castedValue = `${c}['${val.replace('$', '')}'] && ${c}['${val.replace('$', '')}'].bind(${c})`
+    const trimmed = val.trim()
+    if (/^\$?\w+$/.test(trimmed)) {
+      const c = component.slice(0, -1)
+      castedValue = `${c}['${trimmed.replace('$', '')}'] && ${c}['${trimmed.replace('$', '')}'].bind(${c})`
+    } else {
+      castedValue = interpolate(trimmed, component)
+    }
   }
   // dynamic value
   else if (val.startsWith('$')) {

package/src/lib/lifecycle.js

@@ -18,6 +18,9 @@
 import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
 import symbols from './symbols.js'
+import Settings from '../settings.js'
+
+let inspectorEnabled = null
 
 /**
  * List of valid lifecycle states for a component.
@@ -81,9 +84,32 @@ export default {
       privateEmit(v, this.component[symbols.identifier], this.component)
       // 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
+      // update the built-in $hasFocus state variable
+      if (v === 'focus' || v === 'unfocus') {
+        if (inspectorEnabled === null) {
+          inspectorEnabled = Settings.get('inspector', false)
+        }
+      }
+      if (v === 'focus') {
+        this.component[symbols.state].$hasFocus = true
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': true })
+        }
+      }
+      if (v === 'unfocus') {
+        this.component[symbols.state].$hasFocus = false
+        if (
+          inspectorEnabled === true &&
+          this.component[symbols.holder] &&
+          typeof this.component[symbols.holder].setInspectorMetadata === 'function'
+        ) {
+          this.component[symbols.holder].setInspectorMetadata({ 'blits-hasFocus': false })
+        }
+      }
     }
   },
 }

package/src/lib/precompiler/precompiler.js

@@ -17,6 +17,7 @@
 
 import parser from '../templateparser/parser.js'
 import generator from '../codegenerator/generator.js'
+import MagicString from 'magic-string'
 
 export default (source, filePath, mode) => {
   if (
@@ -26,12 +27,9 @@ export default (source, filePath, mode) => {
     /\{.*?template\s*:\s*(['"`])((?:\\?.)*?)\1.*?\}/s.test(source) // object with template key
   ) {
     const templates = source.matchAll(/(?<!\/\/\s*)template\s*:\s*(['"`])((?:\\?.)*?)\1/gs)
-    let newSource = source
-    /*
-      if there are multiple templates in the file, we need to keep
-      track of the offset caused by the previous replacements
-    */
-    let offset = 0
+
+    // Use MagicString to track changes
+    const s = new MagicString(source)
 
     for (const template of templates) {
       if (template[2]) {
@@ -39,7 +37,8 @@ export default (source, filePath, mode) => {
 
         // Only process if it looks like a Blits template
         if (templateContent.match(/^\s*(<!--[\s\S]*?-->|<[A-Za-z][^>]*>)/s)) {
-          const templateStartIndex = template.index + offset
+          // Use original indices - MagicString handles position tracking automatically
+          const templateStartIndex = template.index
           const templateEndIndex = templateStartIndex + template[0].length
 
           // Parse the template
@@ -58,16 +57,26 @@ export default (source, filePath, mode) => {
             (fn) => fn.toString()
           )}], context: {}}`
 
-          offset += replacement.length - template[0].length
-
-          newSource =
-            newSource.substring(0, templateStartIndex) +
-            replacement +
-            newSource.substring(templateEndIndex)
+          // MagicString tracks all changes automatically, no offset needed
+          s.overwrite(templateStartIndex, templateEndIndex, replacement)
         }
       }
     }
-    return newSource
+
+    const newSource = s.toString()
+
+    if (newSource !== source) {
+      const fileName = filePath.split(/[\\/]/).pop()
+      return {
+        code: newSource,
+        map: s.generateMap({
+          hires: true,
+          source: fileName,
+          includeContent: true,
+          file: fileName,
+        }),
+      }
+    }
   }
   return source
 }

package/src/lib/reactivity/effect.js

@@ -32,9 +32,10 @@ const objectMap = new WeakMap()
 const globalEffectsMap = new Map()
 
 export const removeGlobalEffects = (effectsToRemove) => {
-  if (globalEffectsMap.size === 0) return
+  if (globalEffectsMap.size === 0 || effectsToRemove.length === 0) return
+  const effectsToRemoveSet = new Set(effectsToRemove)
   for (const [effect, target] of globalEffectsMap) {
-    if (effectsToRemove.indexOf(effect) === -1) continue
+    if (!effectsToRemoveSet.has(effect)) continue
     const effectsSet = objectMap.get(target)
     if (effectsSet === undefined) continue
     for (const set of effectsSet.values()) {

package/src/lib/reactivityguard/computedprops.js

@@ -35,10 +35,12 @@ const findMatchingBrace = (text, startPos) => {
     // Skip comments when not in strings
     else if (!inString && char === '/' && text[position + 1] === '/') {
       // Skip line comment
-      position = text.indexOf('\n', position) || text.length - 1
+      const nextNewline = text.indexOf('\n', position + 2)
+      position = nextNewline === -1 ? text.length - 1 : nextNewline
     } else if (!inString && char === '/' && text[position + 1] === '*') {
       // Skip block comment
-      position = text.indexOf('*/', position + 2) || text.length - 1
+      const end = text.indexOf('*/', position + 2)
+      position = end === -1 ? text.length - 1 : end + 1
     }
     // Count braces only outside strings and comments
     else if (!inString) {
@@ -60,6 +62,44 @@ const findComputedFunctionEnd = (computedObj, openingBracePos) => {
   return findMatchingBrace(computedObj, openingBracePos)
 }
 
+// Skip whitespace + commas + comments (line and block) starting from `pos`, return next code position.
+const skipNonCode = (text, pos) => {
+  let p = pos
+  while (p < text.length) {
+    const c = text[p]
+
+    // whitespace
+    if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+      p++
+      continue
+    }
+
+    // separators between object members
+    if (c === ',') {
+      p++
+      continue
+    }
+
+    // line comment
+    if (c === '/' && text[p + 1] === '/') {
+      const nextNewline = text.indexOf('\n', p + 2)
+      p = nextNewline === -1 ? text.length : nextNewline + 1
+      continue
+    }
+
+    // block comment
+    if (c === '/' && text[p + 1] === '*') {
+      const end = text.indexOf('*/', p + 2)
+      p = end === -1 ? text.length : end + 2
+      continue
+    }
+
+    return p
+  }
+
+  return p
+}
+
 export default (code) => {
   // Find component declarations
   const componentRegex =
@@ -83,6 +123,8 @@ export default (code) => {
 
       if (computedEnd !== -1) {
         const computedObj = configObject.substring(computedStart, computedEnd)
+        const computedBlockStart = computedKeywordMatch.index
+        const computedBlockEnd = computedEnd
 
         // Process each computed property
         const computedProps = []
@@ -93,15 +135,20 @@ export default (code) => {
         // using cursor-based parsing gives better accuracy
         while (currentPos < computedObj.length - 1) {
           // -1 to exclude the closing brace
-          // Find the next function name
-          const functionNameMatch = /\s*(\w+)\s*\(\)/.exec(computedObj.substring(currentPos))
+          // Skip whitespace/comments so we don't match commented-out computed functions
+          currentPos = skipNonCode(computedObj, currentPos)
+          if (currentPos >= computedObj.length - 1) break
+
+          // Find the next function name (computed properties are `name() { ... }`)
+          const functionNameMatch = /^(\w+)\s*\(\)\s*/.exec(computedObj.substring(currentPos))
           if (!functionNameMatch) break
 
           const funcName = functionNameMatch[1]
-          const funcNamePos = currentPos + functionNameMatch.index
+          const funcNamePos = currentPos
 
           // Find opening brace for this function
-          const openingBracePos = computedObj.indexOf('{', funcNamePos)
+          const afterSignaturePos = funcNamePos + functionNameMatch[0].length
+          const openingBracePos = computedObj.indexOf('{', afterSignaturePos)
           if (openingBracePos === -1) break
 
           // Find closing brace for individual computed function
@@ -133,14 +180,15 @@ export default (code) => {
         }
 
         // Store the original computed object for later replacement
-        const originalComputedObj = configObject.substring(
-          computedStart - 'computed: '.length,
-          computedEnd
-        )
+        const originalComputedObj = configObject.substring(computedBlockStart, computedBlockEnd)
+        const computedObjOffsetInOriginal = computedStart - computedBlockStart
+        const computedObjEndInOriginal = computedObjOffsetInOriginal + computedObj.length
 
         let modifiedComputedObj = originalComputedObj
         let hasChanges = false
 
+        const replacements = []
+
         for (const prop of computedProps) {
           const thisRefs = extractThisReferences(prop.body)
 
@@ -181,13 +229,31 @@ export default (code) => {
                 prop.fullText.substring(0, openBraceIndex).match(/^(\s*)/)[0] +
                 '}'
 
-              // Replace this property in the computed object text
-              modifiedComputedObj = modifiedComputedObj.replace(prop.fullText, modifiedPropText)
-              hasChanges = true
+              replacements.push({
+                start: prop.startPos,
+                end: prop.endPos,
+                text: modifiedPropText,
+              })
             }
           }
         }
 
+        if (replacements.length > 0) {
+          let modifiedComputedInner = computedObj
+
+          replacements.sort((a, b) => b.start - a.start)
+          for (const r of replacements) {
+            modifiedComputedInner =
+              modifiedComputedInner.slice(0, r.start) + r.text + modifiedComputedInner.slice(r.end)
+          }
+
+          modifiedComputedObj =
+            originalComputedObj.slice(0, computedObjOffsetInOriginal) +
+            modifiedComputedInner +
+            originalComputedObj.slice(computedObjEndInOriginal)
+          hasChanges = true
+        }
+
         if (hasChanges) {
           // Store the modification of the entire computed object
           modifications.push({
@@ -213,7 +279,12 @@ export default (code) => {
       modifiedCode = modifiedCode.replace(mod.original, mod.replacement)
     }
 
-    return { code: modifiedCode }
+    // Returning code without a source map
+    // Vite will automatically chain this with the next plugin's source map (preCompiler)
+    return {
+      code: modifiedCode,
+      map: { mappings: '' },
+    }
   }
 
   return null

package/src/lib/shaders/shaders.js

@@ -139,11 +139,12 @@ export default {
       return v
     }
     if (typeof v === 'string') {
-      return colors.normalize(v)
+      return colors.normalize(v, v)
     }
     if (Array.isArray(v) === true) {
       return v.map((i) => this.parseProp(i))
     }
+    return v
   },
   parseProps(v) {
     if (typeof v === 'string') {

package/src/lib/symbols.js

@@ -17,6 +17,7 @@
  * @property {symbol} inputEvents
  * @property {symbol} internalEvent
  * @property {symbol} intervals
+ * @property {symbol} debounces
  * @property {symbol} isProxy
  * @property {symbol} launched
  * @property {symbol} level
@@ -73,6 +74,7 @@ export default {
   inputEvents: Symbol('inputEvents'),
   internalEvent: Symbol('internalEvent'),
   intervals: Symbol('intervals'),
+  debounces: Symbol('debounces'),
   isProxy: Symbol('isProxy'),
   launched: Symbol('launched'),
   level: Symbol('level'),

package/src/plugins/appstate.d.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2024 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
+ */
+
+export type AppStatePlugin<TState extends Record<string, unknown> = Record<string, unknown>> = TState
+
+declare const appState: {
+  readonly name: 'appState'
+  plugin: <TState extends Record<string, unknown>>(state?: TState) => AppStatePlugin<TState>
+}
+
+export default appState
+

package/src/plugins/index.d.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2024 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
+ */
+
+export { default as language } from './language.js'
+export { default as theme } from './theme.js'
+export { default as appState } from './appstate.js'
+export { default as storage } from './storage/storage.js'
+
+// Re-export plugin interfaces for convenience
+export type { LanguagePlugin, LanguagePluginOptions } from './language.js'
+export type { ThemePlugin, ThemePluginConfig } from './theme.js'
+export type { StoragePlugin } from './storage/storage.js'
+export type { AppStatePlugin } from './appstate.js'
+