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

package/src/announcer/speechSynthesis.js

@@ -19,33 +19,61 @@ import { Log } from '../lib/log.js'
 
 const syn = window.speechSynthesis
 
-const isAndroid = /android/i.test((window.navigator || {}).userAgent || '')
-
-const utterances = new Map() // Strong references with unique keys
+const utterances = new Map() // id -> { utterance, timer, ignoreResume }
 
 let initialized = false
-let infinityTimer = null
 
-const clear = () => {
-  if (infinityTimer) {
-    clearTimeout(infinityTimer)
-    infinityTimer = null
+const clear = (id) => {
+  const state = utterances.get(id)
+  if (state === undefined) {
+    return
+  }
+  if (state.timer !== null) {
+    clearTimeout(state.timer)
+    state.timer = null
   }
+  utterances.delete(id)
 }
 
-const resumeInfinity = (target) => {
-  if (!target || infinityTimer) {
-    return clear()
+const startKeepAlive = (id) => {
+  const state = utterances.get(id)
+
+  // utterance status: utterance was removed (cancelled or finished)
+  if (state == undefined) {
+    return
+  }
+
+  // Clear existing timer for this specific utterance
+  if (state.timer !== null) {
+    clearTimeout(state.timer)
+    state.timer = null
+  }
+
+  // syn status: syn might be undefined or cancelled
+  if (!syn) {
+    clear(id)
+    return
   }
 
   syn.pause()
   setTimeout(() => {
-    syn.resume()
+    // utterance status: utterance might have been removed during setTimeout
+    const currentState = utterances.get(id)
+    if (currentState) {
+      currentState.ignoreResume = true
+      syn.resume()
+    }
   }, 0)
 
-  infinityTimer = setTimeout(() => {
-    resumeInfinity(target)
-  }, 5000)
+  // Check if utterance still exists before scheduling next cycle
+  if (utterances.has(id) === true) {
+    state.timer = setTimeout(() => {
+      // Double-check utterance still exists before resuming
+      if (utterances.has(id) === true) {
+        startKeepAlive(id)
+      }
+    }, 5000)
+  }
 }
 
 const defaultUtteranceProps = {
@@ -57,45 +85,124 @@ const defaultUtteranceProps = {
 }
 
 const initialize = () => {
+  // syn api check: syn might not have getVoices method
+  if (!syn || typeof syn.getVoices !== 'function') {
+    initialized = false
+    return
+  }
+
   const voices = syn.getVoices()
   defaultUtteranceProps.voice = voices[0] || null
   initialized = true
 }
 
-const speak = (options) => {
-  const utterance = new SpeechSynthesisUtterance(options.message)
+const waitForSynthReady = (timeoutMs = 2000, checkIntervalMs = 100) => {
+  return new Promise((resolve) => {
+    if (!syn) {
+      Log.debug('SpeechSynthesis - syn unavailable')
+      resolve()
+      return
+    }
+
+    if (!syn.speaking && !syn.pending) {
+      Log.debug('SpeechSynthesis - ready immediately')
+      resolve()
+      return
+    }
+
+    Log.debug('SpeechSynthesis - waiting for ready state...')
+
+    const startTime = Date.now()
+
+    const intervalId = setInterval(() => {
+      const elapsed = Date.now() - startTime
+      const isReady = !syn.speaking && !syn.pending
+
+      if (isReady) {
+        Log.debug(`SpeechSynthesis - ready after ${elapsed}ms`)
+        clearInterval(intervalId)
+        resolve()
+      } else if (elapsed >= timeoutMs) {
+        Log.debug(`SpeechSynthesis - timeout after ${elapsed}ms, forcing ready`, {
+          speaking: syn.speaking,
+          pending: syn.pending,
+        })
+        clearInterval(intervalId)
+        resolve()
+      }
+    }, checkIntervalMs)
+  })
+}
+
+const speak = async (options) => {
+  // options check: missing required options
+  if (!options || !options.message) {
+    return Promise.reject({ error: 'Missing message' })
+  }
+
+  // options check: missing or invalid id
   const id = options.id
+  if (id === undefined || id === null) {
+    return Promise.reject({ error: 'Missing id' })
+  }
+
+  // utterance status: utterance with same id already exists
+  if (utterances.has(id)) {
+    clear(id)
+  }
+
+  // Wait for engine to be ready
+  await waitForSynthReady()
+
+  const utterance = new SpeechSynthesisUtterance(options.message)
   utterance.lang = options.lang || defaultUtteranceProps.lang
   utterance.pitch = options.pitch || defaultUtteranceProps.pitch
   utterance.rate = options.rate || defaultUtteranceProps.rate
   utterance.voice = options.voice || defaultUtteranceProps.voice
   utterance.volume = options.volume || defaultUtteranceProps.volume
-  utterances.set(id, utterance) // Strong reference
-
-  if (isAndroid === false) {
-    utterance.onstart = () => {
-      resumeInfinity(utterance)
-    }
 
-    utterance.onresume = () => {
-      resumeInfinity(utterance)
-    }
-  }
+  utterances.set(id, { utterance, timer: null, ignoreResume: false })
 
   return new Promise((resolve, reject) => {
-    utterance.onend = () => {
-      clear()
-      utterances.delete(id) // Cleanup
-      resolve()
+    utterance.onend = (result) => {
+      clear(id)
+      resolve(result)
     }
 
     utterance.onerror = (e) => {
-      clear()
-      utterances.delete(id) // Cleanup
-      reject(e)
+      Log.warn('SpeechSynthesisUtterance error:', e)
+      clear(id)
+      resolve()
     }
 
-    syn.speak(utterance)
+    if (options.enableUtteranceKeepAlive === true) {
+      utterance.onstart = () => {
+        // utterances status: check if utterance still exists
+        if (utterances.has(id)) {
+          startKeepAlive(id)
+        }
+      }
+
+      utterance.onresume = () => {
+        const state = utterances.get(id)
+        // utterance status: utterance might have been removed
+        if (!state) return
+
+        if (state.ignoreResume === true) {
+          state.ignoreResume = false
+          return
+        }
+
+        startKeepAlive(id)
+      }
+    }
+    // handle error: syn.speak might throw
+    try {
+      syn.speak(utterance)
+    } catch (error) {
+      clear(id)
+      reject(error)
+    }
   })
 }
 
@@ -113,8 +220,20 @@ export default {
   },
   cancel() {
     if (syn !== undefined) {
-      syn.cancel()
-      clear()
+      // timers: clear all timers before cancelling
+      for (const id of utterances.keys()) {
+        clear(id)
+      }
+
+      // handle errors: syn.cancel might throw
+      try {
+        syn.cancel()
+      } catch (error) {
+        Log.error('Error cancelling speech synthesis:', error)
+      }
+
+      // utterances status: ensure all utterances are cleaned up
+      utterances.clear()
     }
   },
   // @todo

package/src/component/base/methods.js

@@ -100,6 +100,8 @@ export default {
       // pass focus to the parent so we don't get lost in focus limbo
       if (this.$hasFocus === true) this[symbols.parent].$focus()
 
+      // @todo - is this really necessary?
+      // This cause an issue with auto sizing of parent (and required an extra eol check there)
       for (let key in this[symbols.state]) {
         if (Array.isArray(this[symbols.state][key])) {
           this[symbols.state][key] = []
@@ -108,6 +110,8 @@ export default {
 
       this.$clearTimeouts()
       this.$clearIntervals()
+      this.$clearDebounces()
+
       eventListeners.removeListeners(this)
 
       const rendererEventListenersLength = this[symbols.rendererEventListeners].length

package/src/component/base/router.js

@@ -23,6 +23,12 @@ export default {
     value: {
       to,
       back,
+      get backNavigation() {
+        return state.backNavigation !== false
+      },
+      set backNavigation(enabled) {
+        state.backNavigation = enabled !== false
+      },
       get currentRoute() {
         return currentRoute
       },

package/src/component/base/timeouts_intervals.js

@@ -96,4 +96,60 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  $debounce: {
+    value: function (name, fn, ms, ...params) {
+      // early exit when component is marked as end of life
+      if (this.eol === true) return
+
+      // clear existing debounce for this name if it exists
+      const existing = this[symbols.debounces].get(name)
+      if (existing !== undefined) {
+        this.$clearTimeout(existing)
+        this[symbols.debounces].delete(name)
+      }
+
+      // create new timeout
+      const timeoutId = setTimeout(() => {
+        this[symbols.debounces].delete(name)
+        this.$clearTimeout(timeoutId)
+        fn.apply(this, params)
+      }, ms)
+
+      // track timeout in timeouts array for automatic cleanup
+      this[symbols.timeouts].push(timeoutId)
+
+      // store timeoutId per name to enable replace behavior and lifecycle cleanup
+      this[symbols.debounces].set(name, timeoutId)
+
+      return timeoutId
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+  $clearDebounce: {
+    value: function (name) {
+      const existing = this[symbols.debounces].get(name)
+      if (existing !== undefined) {
+        this.$clearTimeout(existing)
+        this[symbols.debounces].delete(name)
+      }
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+  $clearDebounces: {
+    value: function () {
+      // clear all timeouts associated with debounces
+      const timeoutIds = Array.from(this[symbols.debounces].values())
+      for (let i = 0; i < timeoutIds.length; i++) {
+        this.$clearTimeout(timeoutIds[i])
+      }
+      this[symbols.debounces].clear()
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
 }

package/src/component/setup/routes.js

@@ -16,12 +16,17 @@
  */
 
 import symbols from '../../lib/symbols.js'
+import { state as routerState } from '../../router/router.js'
 
 export default (component, data) => {
   let routes = data
   if (Array.isArray(data) === false) {
     component[symbols.routerHooks] = data.hooks
     routes = data.routes
+    // Set initial backNavigation value if provided in router config
+    if (data.backNavigation !== undefined) {
+      routerState.backNavigation = data.backNavigation !== false
+    }
   }
   component[symbols.routes] = []
 

package/src/component.js

@@ -229,6 +229,9 @@ const Component = (name = required('name'), config = required('config')) => {
     // create an empty array for storing intervals created by this component (via this.$setInterval)
     this[symbols.intervals] = []
 
+    // create a Map for storing debounced functions (via this.$debounce)
+    this[symbols.debounces] = new Map()
+
     // apply the state function (passing in the this reference to utilize configured props)
     // and store a reference to this original state
     this[symbols.originalState] =
@@ -361,7 +364,7 @@ const Component = (name = required('name'), config = required('config')) => {
           }
         }
 
-        let old = this[key]
+        let old = target[key]
 
         const eff = (force = false) => {
           const newValue = target[key]
@@ -456,6 +459,9 @@ const Component = (name = required('name'), config = required('config')) => {
   // during the code generation step
   factory[Symbol.for('config')] = config
 
+  // Display name for inspector
+  factory[Symbol.for('componentType')] = name
+
   // To determine whether dynamic component is actual Blits component or not
   factory[symbols.isComponent] = true
 

package/src/components/Circle.js

@@ -78,6 +78,7 @@ export default () =>
         let slotChildCounter = 0
         let cmps = []
         elementConfigs[0] = {}
+        elementConfigs[0]['___wrapper'] = true
 
         elms[0] = this.element(
           { parent: parent || 'root' },

package/src/components/FPScounter.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' },

package/src/components/RouterView.js

@@ -16,141 +16,157 @@
  */
 
 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'
 
 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',
+          ]
+          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)
+            }
+          }
+        },
       },
-    },
-  })
+    })
+  )