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

package/src/announcer/announcer.js

@@ -26,7 +26,9 @@ let currentId = null
 let debounce = null
 
 // Global default utterance options
-let globalDefaultOptions = {}
+let globalDefaultOptions = {
+  enableUtteranceKeepAlive: !/android/i.test((window.navigator || {}).userAgent || ''),
+}
 
 const noopAnnouncement = {
   then() {},
@@ -50,7 +52,6 @@ const toggle = (v) => {
 
 const speak = (message, politeness = 'off', options = {}) => {
   if (active === false) return noopAnnouncement
-
   return addToQueue(message, politeness, false, options)
 }
 
@@ -106,6 +107,8 @@ const addToQueue = (message, politeness, delay = false, options = {}) => {
   return done
 }
 
+let currentResolveFn = null
+
 const processQueue = async () => {
   if (isProcessing === true || queue.length === 0) return
   isProcessing = true
@@ -113,11 +116,13 @@ const processQueue = async () => {
   const { message, resolveFn, delay, id, options = {} } = queue.shift()
 
   currentId = id
+  currentResolveFn = resolveFn
 
   if (delay) {
     setTimeout(() => {
       isProcessing = false
       currentId = null
+      currentResolveFn = null
       resolveFn('finished')
       processQueue()
     }, delay)
@@ -138,19 +143,23 @@ const processQueue = async () => {
           Log.debug(`Announcer - finished speaking: "${message}" (id: ${id})`)
 
           currentId = null
+          currentResolveFn = null
           isProcessing = false
           resolveFn('finished')
           processQueue()
         })
         .catch((e) => {
-          currentId = null
-          isProcessing = false
+          if (id === currentId) {
+            currentId = null
+            currentResolveFn = null
+            isProcessing = false
+          }
           Log.debug(`Announcer - error ("${e.error}") while speaking: "${message}" (id: ${id})`)
           resolveFn(e.error)
           processQueue()
         })
       debounce = null
-    }, 200)
+    }, 300)
   }
 }
 
@@ -158,13 +167,52 @@ const polite = (message, options = {}) => speak(message, 'polite', options)
 
 const assertive = (message, options = {}) => speak(message, 'assertive', options)
 
+// Clear debounce timer
+const clearDebounceTimer = () => {
+  if (debounce !== null) {
+    clearTimeout(debounce)
+    debounce = null
+  }
+}
+
 const stop = () => {
+  // Clear debounce timer if speech hasn't started yet
+  clearDebounceTimer()
+
+  // Always cancel speech synthesis to ensure clean state
   speechSynthesis.cancel()
+
+  // Store resolve function before resetting state
+  const resolveFn = currentResolveFn
+
+  // Reset state
+  currentId = null
+  currentResolveFn = null
+  isProcessing = false
+
+  // Resolve promise if there was an active utterance
+  if (resolveFn !== null) {
+    resolveFn('interrupted')
+  }
 }
 
 const clear = () => {
+  // Clear debounce timer
+  clearDebounceTimer()
+
+  // Resolve all pending items in queue
+  while (queue.length > 0) {
+    const item = queue.shift()
+    if (item.resolveFn) {
+      Log.debug(`Announcer - clearing queued item: "${item.message}" (id: ${item.id})`)
+      item.resolveFn('cleared')
+    }
+  }
+
+  // Reset state
+  currentId = null
+  currentResolveFn = null
   isProcessing = false
-  queue.length = 0
 }
 
 const configure = (options = {}) => {

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/application.js

@@ -15,12 +15,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import Component from './component.js'
-import { default as Focus, keyUpCallbacks } from './focus.js'
-import Settings from './settings.js'
+import { default as Component, componentMap } from './component.js'
+import { default as Focus, keyUpCallbacks } from './focus/focus.js'
+import Hover from './focus/hover.js'
 
+import Settings from './settings.js'
 import symbols from './lib/symbols.js'
 import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
+import { renderer } from './launch.js'
 
 /**
  * Merged keyMap (default + custom settings).
@@ -34,13 +36,27 @@ const Application = (config) => {
 
   let keyDownHandler
   let keyUpHandler
+  let mouseMoveHandler
+  let mouseClickHandler
+  let updateCanvasRect
   let holdTimeout
   let lastInputTime = 0
   let lastInputKey = null
+  let mouseListenersAdded = false
 
   config.hooks[symbols.destroy] = function () {
+    // Cancel pending key-hold timeout and reset hold state so focus is not left in hold mode after teardown
+    clearTimeout(holdTimeout)
+    Focus.hold = false
     document.removeEventListener('keydown', keyDownHandler)
     document.removeEventListener('keyup', keyUpHandler)
+    if (mouseListenersAdded) {
+      document.removeEventListener('mousemove', mouseMoveHandler)
+      document.removeEventListener('click', mouseClickHandler)
+      window.removeEventListener('resize', updateCanvasRect)
+      window.removeEventListener('scroll', updateCanvasRect)
+      Hover.clear()
+    }
   }
 
   config.hooks[symbols.init] = function () {
@@ -57,6 +73,8 @@ const Application = (config) => {
     /** @type {number} Input throttle time in milliseconds (0 = disabled) */
     const throttleMs = Settings.get('inputThrottle', 0)
 
+    const mouseEnabled = Settings.get('enableMouse', false)
+
     keyDownHandler = async (e) => {
       const currentTime = performance.now()
 
@@ -89,6 +107,7 @@ const Application = (config) => {
       }
 
       Focus.input(key, e)
+      if (mouseEnabled === true) Hover.clear()
       clearTimeout(holdTimeout)
       holdTimeout = setTimeout(
         () => {
@@ -108,8 +127,84 @@ const Application = (config) => {
       Focus.hold = false
     }
 
+    let lastMoved = 0
+    let currentNode = undefined
+    let currentComponent = undefined
+    let canvasRect = null
+
+    updateCanvasRect = () => {
+      if (renderer.canvas !== undefined) {
+        canvasRect = renderer.canvas.getBoundingClientRect()
+      }
+    }
+
+    // limit the amount of move events per time frame
+    mouseMoveHandler = (e) => {
+      if (e.timeStamp - lastMoved < 100) return
+      lastMoved = e.timeStamp
+
+      this.$emit('mouse::move', e)
+
+      if (canvasRect === null && renderer.canvas != null) {
+        updateCanvasRect()
+      }
+      if (canvasRect === null) {
+        return
+      }
+
+      const stage = renderer.stage
+      if (stage == null) {
+        return
+      }
+
+      // Convert viewport → canvas display coordinates
+      const x = e.clientX - canvasRect.left
+      const y = e.clientY - canvasRect.top
+
+      const node = stage.getNodeFromPosition({ x, y })
+
+      if (node === null) {
+        currentComponent = undefined
+        Hover.clear()
+        return
+      }
+      if (node === currentNode) return
+
+      currentNode = node
+      currentComponent = componentMap.get(currentNode)
+
+      if (currentComponent === undefined) {
+        Hover.clear()
+        return
+      }
+      Hover.set(currentComponent)
+    }
+
+    mouseClickHandler = () => {
+      if (currentComponent === undefined || currentComponent.eol === true) return
+
+      const e = new KeyboardEvent('keydown', {
+        key: 'Enter',
+        code: 'Enter',
+        keyCode: 13,
+        bubbles: true,
+        cancelable: true,
+        composed: true,
+      })
+      currentComponent.$focus()
+      currentComponent.$input(e)
+    }
+
     document.addEventListener('keydown', keyDownHandler)
     document.addEventListener('keyup', keyUpHandler)
+    if (mouseEnabled === true) {
+      updateCanvasRect()
+      document.addEventListener('mousemove', mouseMoveHandler)
+      document.addEventListener('click', mouseClickHandler)
+      window.addEventListener('resize', updateCanvasRect)
+      window.addEventListener('scroll', updateCanvasRect)
+      mouseListenersAdded = true
+    }
 
     // next tick
     setTimeout(() => Focus.set(this))

package/src/component/base/methods.js

@@ -16,8 +16,7 @@
  */
 
 import symbols from '../../lib/symbols.js'
-import Focus from '../../focus.js'
-import { keyUpCallbacks, getComponentWithInputEvent } from '../../focus.js'
+import { default as Focus, keyUpCallbacks, getComponentWithInputEvent } from '../../focus/focus.js'
 import eventListeners from '../../lib/eventListeners.js'
 import { trigger } from '../../lib/reactivity/effect.js'
 import { Log } from '../../lib/log.js'
@@ -100,6 +99,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 +109,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/setup/state.js

@@ -36,6 +36,8 @@ export default (component, state = () => {}) => {
     // add built-in $hasFocus key
     stateKeys.push('$hasFocus')
   }
+  // add built-in isHovered key
+  stateKeys.push(['$isHovered'])
   const stateKeysLength = stateKeys.length
 
   for (let i = 0; i < stateKeysLength; i++) {