@lightningjs/blits 2.14.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -58,8 +58,8 @@
   },
   "scripts": {
     "test": "c8 npm run test:run | tap-diff",
-    "test:run": "node -r global-jsdom/register node_modules/tape/bin/tape \"scripts/**/*.test.js\" \"src/**/*.test.js\"",
-    "test:run:failures": "node -r global-jsdom/register node_modules/tape/bin/tape \"scripts/**/*.test.js\" \"src/**/*.test.js\" | tap-filter test-fail | tap-diff",
+    "test:run": "node -r global-jsdom/register node_modules/tape/bin/tape \"scripts/**/*.test.js\" \"src/**/*.test.js\" \"vite/**/*.test.js\"",
+    "test:run:failures": "node -r global-jsdom/register node_modules/tape/bin/tape \"scripts/**/*.test.js\" \"src/**/*.test.js\" \"vite/**/*.test.js\" | tap-filter test-fail | tap-diff",
     "lint": "node scripts/lint.js",
     "lint:fix": "node scripts/lint.js fix",
     "prepublishOnly": "node scripts/prepublishOnly.js",
@@ -70,7 +70,7 @@
     "bench:compare": "npm --prefix benchmarks run bench:compare --",
     "bench:profile": "npm --prefix benchmarks run bench:profile --",
     "bench:serve": "npm --prefix benchmarks run serve",
-    "release": "npm publish --access public"
+    "release": "node scripts/release.js"
   },
   "types": "./index.d.ts",
   "lint-staged": {
@@ -95,7 +95,7 @@
     "globals": "^17.12.0",
     "husky": "^9.1.7",
     "jsdom": "^30.1.0",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "^17.6.0",
     "prettier": "^3.6.2",
     "sinon": "^22.1.0",
     "tap-diff": "^0.1.1",
@@ -103,7 +103,7 @@
     "tape": "^5.9.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "^3.7.0",
+    "@lightningjs/renderer": "3.11.0",
     "magic-string": "^1.4.1"
   },
   "repository": {

package/src/application.js

@@ -24,16 +24,79 @@ import symbols from './lib/symbols.js'
 import { DEFAULT_HOLD_TIMEOUT_MS, DEFAULT_KEYMAP } from './constants.js'
 import { renderer } from './launch.js'
 import { platform } from './platform.js'
+import { keyMap, setKeyMap } from './keymap.js'
 
-/**
- * Merged keyMap (default + custom settings).
- * Initialized once during application init.
- * @type {Object<string, string>}
- */
-export let keyMap = {}
+export { keyMap } from './keymap.js'
+
+// Reacts to Blits-only settings changed at runtime via `this.$settings.set()`.
+Settings.onRuntimeSettingChange = (key, value) => {
+  if (key === 'keymap') {
+    initKeyMap()
+    return
+  }
+
+  if (key === 'inputThrottle') {
+    inputThrottleMs = value
+    return
+  }
+
+  if (key === 'mouseMoveThrottle') {
+    mouseMoveThrottleMs = value
+    return
+  }
+
+  if (
+    key === 'announcerOptions' &&
+    liveAppInstance &&
+    liveAppInstance.$announcer &&
+    value &&
+    typeof value === 'object'
+  ) {
+    liveAppInstance.$announcer.configure(value)
+    return
+  }
+
+  if (key === 'enableMouse') {
+    enableMouseFlag = value
+    if (liveInput !== null && liveViewport !== null) {
+      if (value === true && mouseListenersAttached === false) {
+        liveInput.addEventListener('mousemove', mouseMoveHandlerRef)
+        liveInput.addEventListener('click', mouseClickHandlerRef)
+        liveViewport.addEventListener('resize', updateCanvasRectRef)
+        liveViewport.addEventListener('scroll', updateCanvasRectRef)
+        mouseListenersAttached = true
+      } else if (value === false && mouseListenersAttached === true) {
+        liveInput.removeEventListener('mousemove', mouseMoveHandlerRef)
+        liveInput.removeEventListener('click', mouseClickHandlerRef)
+        liveViewport.removeEventListener('resize', updateCanvasRectRef)
+        liveViewport.removeEventListener('scroll', updateCanvasRectRef)
+        mouseListenersAttached = false
+        Hover.clear()
+      }
+    }
+  }
+}
+
+/** @type {any} Active App component instance, set during App init */
+let liveAppInstance = null
+/** @type {any} Platform input target, set during App init */
+let liveInput = null
+/** @type {any} Platform viewport target, set during App init */
+let liveViewport = null
+let mouseListenersAttached = false
+/** @type {((e: any) => void)|null} */
+let mouseMoveHandlerRef = null
+/** @type {(() => void)|null} */
+let mouseClickHandlerRef = null
+/** @type {(() => void)|null} */
+let updateCanvasRectRef = null
+
+let inputThrottleMs = 0
+let mouseMoveThrottleMs = 100
+let enableMouseFlag = false
 
 export const initKeyMap = () => {
-  keyMap = { ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) }
+  setKeyMap({ ...DEFAULT_KEYMAP, ...Settings.get('keymap', {}) })
 }
 
 const Application = (config) => {
@@ -66,6 +129,7 @@ const Application = (config) => {
   }
 
   config.hooks[symbols.init] = function () {
+    liveAppInstance = this
     // set the initial activation state of the announcer based on launch setting
     this.$announcer.toggle(Settings.get('announcer', false))
     // configure global default utterance options if provided in settings
@@ -75,15 +139,15 @@ const Application = (config) => {
     }
     // Initialize merged keyMap once during application init
     initKeyMap()
-
-    /** @type {number} Input throttle time in milliseconds (0 = disabled) */
-    const throttleMs = Settings.get('inputThrottle', 0)
-
-    const mouseEnabled = Settings.get('enableMouse', false)
-    const mouseMoveThrottle = Settings.get('mouseMoveThrottle', 100)
+    // Initialize fast-path cached settings once during application init
+    inputThrottleMs = Settings.get('inputThrottle', 0)
+    mouseMoveThrottleMs = Settings.get('mouseMoveThrottle', 100)
+    enableMouseFlag = Settings.get('enableMouse', false)
     const { createKeyboardEvent, input, isKeyboardEvent, now = Date.now, viewport } = platform
+    liveInput = input
+    liveViewport = viewport
 
-    keyDownHandler = async (e) => {
+    keyDownHandler = async (/** @type {any} */ e) => {
       const currentTime = now()
 
       const key = keyMap[e.keyCode] || e.keyCode
@@ -91,11 +155,11 @@ const Application = (config) => {
       lastInputKey = key
       // execute immediately when no throttle is specified or event is internal (bubbled up by focus manager)
       // or key is different from the last used key
-      if (throttleMs === 0 || e[symbols.internalEvent] === true || sameKey === false) {
+      if (inputThrottleMs === 0 || e[symbols.internalEvent] === true || sameKey === false) {
         return await processInput.call(this, e, key)
       }
 
-      if (currentTime - lastInputTime < throttleMs) {
+      if (currentTime - lastInputTime < inputThrottleMs) {
         return
       }
 
@@ -115,7 +179,7 @@ const Application = (config) => {
       }
 
       Focus.input(key, e)
-      if (mouseEnabled === true) {
+      if (enableMouseFlag === true) {
         Hover.clear()
         // forget the node under the pointer too, so moving on it hovers it again
         currentNode = undefined
@@ -130,6 +194,9 @@ const Application = (config) => {
     }
 
     keyUpHandler = (e) => {
+      clearTimeout(holdTimeout)
+      Focus.hold = false
+
       const entry = keyUpCallbacks.get(e.keyCode)
       if (entry !== undefined) {
         keyUpCallbacks.delete(e.keyCode)
@@ -137,8 +204,6 @@ const Application = (config) => {
           entry.callback()
         }
       }
-      clearTimeout(holdTimeout)
-      Focus.hold = false
     }
 
     let lastMoved = 0
@@ -154,7 +219,7 @@ const Application = (config) => {
 
     // limit the amount of move events per time frame
     mouseMoveHandler = (e) => {
-      if (e.timeStamp - lastMoved < mouseMoveThrottle) return
+      if (e.timeStamp - lastMoved < mouseMoveThrottleMs) return
       lastMoved = e.timeStamp
 
       this.$emit('mouse::move', e)
@@ -166,7 +231,7 @@ const Application = (config) => {
         return
       }
 
-      const stage = renderer.stage
+      const stage = /** @type {any} */ (renderer).stage
       if (stage == null) {
         return
       }
@@ -179,6 +244,7 @@ const Application = (config) => {
 
       if (node === null) {
         currentComponent = undefined
+        currentNode = null
         Hover.clear()
         return
       }
@@ -215,16 +281,21 @@ const Application = (config) => {
       input.addEventListener('keydown', keyDownHandler)
       input.addEventListener('keyup', keyUpHandler)
       inputCleanup = () => {
-        input.removeEventListener('keydown', keyDownHandler)
-        input.removeEventListener('keyup', keyUpHandler)
+        input.removeEventListener('keydown', /** @type {any} */ (keyDownHandler))
+        input.removeEventListener('keyup', /** @type {any} */ (keyUpHandler))
       }
     }
-    if (mouseEnabled === true && input !== undefined && viewport !== undefined) {
+    mouseMoveHandlerRef = mouseMoveHandler
+    mouseClickHandlerRef = mouseClickHandler
+    updateCanvasRectRef = updateCanvasRect
+
+    if (enableMouseFlag === true && input !== undefined && viewport !== undefined) {
       updateCanvasRect()
       input.addEventListener('mousemove', mouseMoveHandler)
       input.addEventListener('click', mouseClickHandler)
       viewport.addEventListener('resize', updateCanvasRect)
       viewport.addEventListener('scroll', updateCanvasRect)
+      mouseListenersAttached = true
       mouseCleanup = () => {
         input.removeEventListener('mousemove', mouseMoveHandler)
         input.removeEventListener('click', mouseClickHandler)
@@ -233,8 +304,9 @@ const Application = (config) => {
       }
     }
 
-    // next tick
-    setTimeout(() => Focus.set(this))
+    // focus once the component tree is built (microtask: runs right after the
+    // current instantiation finishes, without yielding to render-loop frames)
+    Promise.resolve().then(() => Focus.set(this))
   }
 
   return Component('App', config)

package/src/component/base/index.js

@@ -21,6 +21,7 @@ import events from './events.js'
 import router from './router.js'
 import announcer from './announcer.js'
 import utils from './utils.js'
+import settings from './settings.js'
 import symbols from '../../lib/symbols.js'
 import { reactive } from '../../lib/reactivity/reactive.js'
 import Settings from '../../settings.js'
@@ -29,6 +30,7 @@ export const shared = {
   ...events,
   ...router,
   ...announcer,
+  ...settings,
   $reactive: {
     value: function (target) {
       return reactive(target, Settings.get('reactivityMode'), true)

package/src/component/base/methods.js

@@ -27,7 +27,7 @@ import { trigger } from '../../lib/reactivity/effect.js'
 import { Log } from '../../lib/log.js'
 import { removeEffects } from '../../lib/reactivity/effect.js'
 import { renderer } from '../../launch.js'
-import { keyMap } from '../../application.js'
+import { keyMap } from '../../keymap.js'
 import { platform } from '../../platform.js'
 
 const selectCache = new WeakMap()

package/src/component/base/router.js

@@ -149,9 +149,9 @@ const createRouter = (component, routerViewName) => {
       toRouterView(routerView, path, data, options)
       return true
     },
-    back() {
+    back(steps = 1) {
       const routerView = resolveRouterView(component, routerViewName)
-      return routerView === null ? false : back.call(routerView)
+      return routerView === null ? false : back.call(routerView, steps)
     },
     get(name) {
       return getRouterFromCache(component, name)
@@ -172,6 +172,10 @@ const createRouter = (component, routerViewName) => {
     get navigating() {
       return state.navigating
     },
+    get history() {
+      const routerView = resolveRouterView(component, routerViewName)
+      return routerView === null ? [] : routerView.history.slice()
+    },
     state,
   }
 }

package/src/component/base/settings.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2023 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 engine from '../../engine.js'
+import { Log } from '../../lib/log.js'
+
+// Settings that can be changed at runtime via `this.$settings.set()`.
+const blitsKeys = [
+  'keymap',
+  'debugLevel',
+  'inputThrottle',
+  'announcerOptions',
+  'enableMouse',
+  'mouseMoveThrottle',
+]
+
+const rendererKeys = [
+  'w',
+  'h',
+  'screenResolution',
+  'renderQuality',
+  'pixelRatio',
+  'canvasColor',
+  'viewportMargin',
+  'maxFPS',
+  'fpsInterval',
+]
+
+const changeableKeys = [...blitsKeys, ...rendererKeys]
+
+export default {
+  $settings: {
+    value: {
+      get(key, defaultValue) {
+        return Settings.get(key, defaultValue)
+      },
+      set(key, value) {
+        if (changeableKeys.indexOf(key) === -1) {
+          Log.warn(`Setting "${key}" can not be changed at runtime`)
+          return
+        }
+        Settings.set(key, value)
+
+        if (rendererKeys.indexOf(key) !== -1) {
+          engine.updateSetting(key, value)
+        }
+      },
+    },
+    writable: false,
+    enumerable: true,
+    configurable: false,
+  },
+}

package/src/component/setup/computed.js

@@ -18,6 +18,7 @@
 import { Log } from '../../lib/log.js'
 
 import symbols from '../../lib/symbols.js'
+import { createComputed } from '../../lib/reactivity/effect.js'
 
 export default (component, computeds) => {
   component[symbols.computedKeys] = []
@@ -40,7 +41,10 @@ export default (component, computeds) => {
       component[symbols.computedKeys].push(computed)
       Object.defineProperty(component, computed, {
         get() {
-          return computeds[computed].apply(this)
+          // Setup runs on the shared prototype; install the cache on first instance access.
+          const get = createComputed(computeds[computed], this, computed)
+          Object.defineProperty(this, computed, { get })
+          return get()
         },
       })
     }

package/src/component.js

@@ -426,8 +426,9 @@ const Component = (name = required('name'), config = required('config')) => {
       }
     }
 
-    // finaly set the lifecycle state to ready (in the next tick)
-    setTimeout(() => (this[symbols.lifecycle].state = 'ready'))
+    // finally set the lifecycle state to ready (synchronously: instantiation,
+    // reactivity setup and template spawn are all complete at this point)
+    this[symbols.lifecycle].state = 'ready'
 
     // and return this
     return this
@@ -495,16 +496,24 @@ const Component = (name = required('name'), config = required('config')) => {
       base = setupComponent(Object.create(Base), config)
     }
 
-    // one time code generation (only if precompilation is turned off)
-    if (config.code === undefined) {
-      Log.debug(`Generating code for ${name} component`)
-      config.code = codegenerator.call(config, parser(config.template, name), devMode)
-    }
+    // Direct factory calls also prepare runtime code before rendering.
+    if (factory.prepare !== undefined) factory.prepare()
 
     // create an instance of the component, using base as the prototype (which contains Base)
     return component.call(Object.create(base), options, parentEl, parentComponent, rootComponent)
   }
 
+  // Precompiled factories have no preparation step. Runtime factories compile once,
+  // explicitly before holder creation, then take the same path as precompiled ones.
+  if (config.code === undefined) {
+    factory.prepare = () => {
+      Log.debug(`Generating code for ${name} component`)
+      config.code = codegenerator.call(config, parser(config.template, name), devMode)
+      factory.needsInteractive = factory.needsInteractive || !!config.code.usesHoverState
+      factory.prepare = undefined
+    }
+  }
+
   // store the config on the factory, in order to access the config
   // during the code generation step
   factory[Symbol.for('config')] = config
@@ -515,6 +524,13 @@ const Component = (name = required('name'), config = required('config')) => {
   // To determine whether dynamic component is actual Blits component or not
   factory[symbols.isComponent] = true
 
+  // Pointer hit testing supports both hover and click-to-focus/input.
+  factory.needsInteractive =
+    (config.hooks && !!(config.hooks.hover || config.hooks.unhover)) ||
+    (config.input &&
+      (typeof config.input.enter === 'function' || typeof config.input.any === 'function')) ||
+    !!(config.code && config.code.usesHoverState)
+
   return factory
 }
 

package/src/components/Circle.js

@@ -66,7 +66,7 @@ export default () =>
           'content',
           'placement',
           'inspector-data',
-          'holder',
+          'interactive',
         ]
         const elementConfigs = []
         const forloops = []
@@ -133,6 +133,7 @@ export default () =>
         },
       ],
       context: {},
+      usesHoverState: false,
     },
     props: { size: 40, bgColor: 'white' },
     computed: {

package/src/components/FPScounter.js

@@ -16,11 +16,15 @@
  */
 
 import Blits from '../../index.js'
-import { renderer } from '../launch.js'
 import fps_sprite from '../../public/assets/fps_sprite.base64.js'
 
 // exporting as named export to allow selective importing
 export const FPScounter = Blits.Component('FPScounter', {
+  props: {
+    active: true,
+    show: true,
+    alpha: 1,
+  },
   /* eslint-disable no-unused-vars */
   code: {
     render: function anonymous(parent, component, context, components, effect, getRaw, Log) {
@@ -68,7 +72,7 @@ export const FPScounter = Blits.Component('FPScounter', {
         'content',
         'placement',
         'inspector-data',
-        'holder',
+        'interactive',
       ]
       const elementConfigs = []
       const forloops = []
@@ -630,6 +634,7 @@ export const FPScounter = Blits.Component('FPScounter', {
       },
     ],
     context: {},
+    usesHoverState: false,
   },
   state() {
     return {
@@ -662,28 +667,34 @@ export const FPScounter = Blits.Component('FPScounter', {
       avgFps: '---',
       minFps: '---',
       maxFps: '---',
+
+      data: {
+        minFps: 10000,
+        maxFps: 0,
+        totalFps: 0,
+        fpsUpdateCounter: 0,
+        avgFps: 0,
+      },
     }
   },
   hooks: {
-    ready() {
-      let minFps = 10000
-      let maxFps = 0
-      let avgFps = 0
-      let totalFps = 0
-      let fpsUpdateCounter = 0
-
-      renderer.on('fpsUpdate', (rM, { fps }) => {
-        minFps = Math.min(fps, minFps)
-        maxFps = Math.max(fps, maxFps)
-        totalFps += fps
-        fpsUpdateCounter++
-        avgFps = Math.round(totalFps / fpsUpdateCounter)
-
-        this.fps = fps.toString().padStart(3, '0')
-        this.avgFps = avgFps.toString().padStart(3, '0')
-        this.minFps = minFps.toString().padStart(3, '0')
-        this.maxFps = maxFps.toString().padStart(3, '0')
-      })
+    /**
+     * @param {number} fps
+     */
+    fpsUpdate(fps) {
+      // early return when not active or hidden
+      if (!this.active || !this.show || this.alpha === 0) return
+
+      this.data.minFps = Math.min(fps, this.data.minFps)
+      this.data.maxFps = Math.max(fps, this.data.maxFps)
+      this.data.totalFps += fps
+      this.data.fpsUpdateCounter++
+      this.data.avgFps = Math.round(this.data.totalFps / this.data.fpsUpdateCounter)
+
+      this.fps = fps.toString().padStart(3, '0')
+      this.avgFps = this.data.avgFps.toString().padStart(3, '0')
+      this.minFps = this.data.minFps.toString().padStart(3, '0')
+      this.maxFps = this.data.maxFps.toString().padStart(3, '0')
     },
   },
 })

package/src/components/RouterView.js

@@ -78,7 +78,7 @@ export default () =>
             'content',
             'placement',
             'inspector-data',
-            'holder',
+            'interactive',
           ]
           const elementConfigs = []
           const forloops = []
@@ -130,6 +130,7 @@ export default () =>
         },
         effects: [],
         context: {},
+        usesHoverState: false,
       },
       props: {
         name: '',

package/src/engines/L3/element.js

@@ -585,7 +585,7 @@ const propsTransformer = {
       this.props['data'] = v
     }
   },
-  set holder(v) {
+  set interactive(v) {
     this.props['interactive'] = v
   },
 }

package/src/engines/L3/index.js

@@ -16,9 +16,47 @@
  */
 
 import Element from './element.js'
-import Launch from './launch.js'
+import Launch, { renderer } from './launch.js'
+import colors from '../../lib/colors/colors.js'
+import { SCREEN_RESOLUTIONS, RENDER_QUALITIES } from '../../constants.js'
+
+/**
+ * Maps Blits setting keys to renderer runtime options
+ *
+ * @type {Record<string, (value: any) => Partial<import('@lightningjs/renderer').RendererRuntimeSettings>>}
+ */
+const rendererOptions = {
+  // defaults to transparent (same as on launch) for empty or invalid colors
+  w: (v) => ({ appWidth: v }),
+  h: (v) => ({ appHeight: v }),
+  screenResolution: (v) => ({
+    deviceLogicalPixelRatio: typeof v === 'string' ? (SCREEN_RESOLUTIONS[v] ?? 1) : v,
+  }),
+  renderQuality: (v) => ({
+    devicePhysicalPixelRatio: RENDER_QUALITIES[v] ?? v ?? 1,
+  }),
+  canvasColor: (v) => ({ clearColor: Number(colors.normalize(v ?? '', '0x00000000')) }),
+  fpsInterval: (v) => ({ fpsUpdateInterval: v }),
+  pixelRatio: (v) => ({ deviceLogicalPixelRatio: v }),
+  viewportMargin: (v) => ({ boundsMargin: v }),
+  maxFPS: (v) => ({ targetFPS: v }),
+}
+
+/**
+ * Applies a runtime setting to the renderer via RendererMain.setOptions()
+ *
+ * @param {string} key - Blits setting key (validated by $settings)
+ * @param {any} value - New value
+ */
+const updateSetting = (key, value) => {
+  const rendererInstance = renderer
+  if (rendererInstance && typeof rendererInstance.setOptions === 'function') {
+    rendererInstance.setOptions(rendererOptions[key](value))
+  }
+}
 
 export default {
   Element,
   Launch,
+  updateSetting,
 }