@lightningjs/blits 1.51.0 → 2.0.0-beta.10

package/index.d.ts

@@ -18,6 +18,10 @@
 // blits file type reference
 /// <reference path="./blits.d.ts" />
 
+import {type ShaderEffect as RendererShaderEffect, type RendererMainSettings} from '@lightningjs/renderer'
+import { CanvasShaderType } from '@lightningjs/renderer/canvas';
+import { WebGlShaderType } from '@lightningjs/renderer/webgl';
+
 declare module '@lightningjs/blits' {
   type RendererShaderEffect = import('@lightningjs/renderer').ShaderEffect
   type WebGlCoreShader = import('@lightningjs/renderer').WebGlCoreShader
@@ -394,14 +398,21 @@ declare module '@lightningjs/blits' {
     *
     * @returns Boolean
     */
-    hasFocus: boolean,
+    readonly $hasFocus: boolean,
+
+    /**
+     * Parent component instance.
+     * Note: will be undefined for the root Application component or after destroy.
+     *
+     */
+    readonly $parent: ComponentBase,
 
     /**
     * Indicates whether the component currently is hovered
     *
     * @returns Boolean
     */
-    isHovered: boolean,
+    $isHovered: boolean,
 
     /**
     * Listen to events emitted by other components
@@ -490,12 +501,6 @@ declare module '@lightningjs/blits' {
      * @returns Returns true if this component or a parent component handled the event, false otherwise
      */
     $input: (event: KeyboardEvent) => boolean
-    /**
-     * @deprecated
-     * Deprecated:  use `this.$focus()` instead
-     */
-    focus: (event?: KeyboardEvent) => void
-
     /**
     * Select a child Element or Component by ref
     *
@@ -513,12 +518,6 @@ declare module '@lightningjs/blits' {
     */
     $select: (ref: string) => ComponentBase
 
-    /**
-     * @deprecated
-     * Deprecated: use `this.$select()` instead
-     */
-    select: (ref: string) => ComponentBase
-
     /**
      * Announcer methods for screen reader support
      */
@@ -528,13 +527,6 @@ declare module '@lightningjs/blits' {
      * Triggers a forced update on state variables.
      */
     $trigger: (key: string) => void
-    /**
-     * @deprecated
-     *
-     * Triggers a forced update on state variables.
-     * Deprecated: use `this.$trigger()` instead
-     */
-    trigger: (key: string) => void
     /**
      * Router instance
      */
@@ -584,20 +576,22 @@ declare module '@lightningjs/blits' {
     cast?: () => any
   };
 
-  // Props Array
-  export type Props = (string | PropObject)[];
+  export type Props = Record<string, any>
 
-  // Extract the prop names from the props array
-  type ExtractPropNames<P extends Props> = {
-      readonly [K in P[number] as K extends string ? K : K extends { key: infer Key } ? Key : never]: any;
-  };
+  type InferProp<T> = T extends (...args: any[]) => any ? ReturnType<T> : T
 
-  // Update the PropsDefinition to handle props as strings or objects
-  export type PropsDefinition<P extends Props> = ExtractPropNames<P>;
+  type InferProps<T extends Record<string, any>> = {
+    [K in keyof T]: InferProp<T[K]>
+  }
 
-  export type ComponentContext<P extends Props, S, M, C> = ThisType<PropsDefinition<P> & S & M & C & ComponentBase>
+  export type ComponentContext<
+    P extends Record<string, any>,
+    S,
+    M,
+    C
+  > = ThisType<Readonly<InferProps<P>> & S & M & Readonly<C> & ComponentBase>
 
-  export interface ComponentConfig<P extends Props, S, M, C, W> {
+  export interface ComponentConfig<P extends Props = {}, S, M, C, W> {
     components?: {
         [key: string]: ComponentFactory,
     },
@@ -653,7 +647,7 @@ declare module '@lightningjs/blits' {
      * }
      * ```
      */
-    state?: (this: PropsDefinition<P>) => S;
+    state?: (this: Readonly<InferProps<P>> & ComponentBase) => S;
     /**
      * Methods for abstracting more complex business logic into separate function
      */
@@ -942,7 +936,7 @@ declare module '@lightningjs/blits' {
 
   type Shader = {
     name: string,
-    type: WebGlCoreShader
+    type: WebGlShaderType | CanvasShaderType
   }
 
   type ScreenResolutions = 'hd' | '720p' | 720 | 'fhd' | 'fullhd' | '1080p' | 1080 | '4k' | '2160p' | 2160
@@ -978,10 +972,6 @@ declare module '@lightningjs/blits' {
      * Fonts to be used in the Application
      */
     fonts?: Font[],
-    /**
-     * Effects to be used by DynamicShader
-     */
-    effects?: ShaderEffect[],
     /**
      * Shaders to be used in the application
      */
@@ -1114,18 +1104,6 @@ declare module '@lightningjs/blits' {
      * Defaults to `0`
      */
     viewportMargin?: number | [number, number, number, number],
-    /**
-     * Threshold in `Megabytes` after which all the textures that are currently not visible
-     * within the configured viewport margin will be be freed and cleaned up
-     *
-     * When passed `0` the threshold is disabled and textures will not be actively freed
-     * and cleaned up
-     *
-     * Defaults to `200` (mb)
-     * @deprecated
-     * Deprecated:  use `gpuMemory` launch setting instead
-     */
-    gpuMemoryLimit?: number,
     /**
      * Configures the gpu memory settings used by the renderer
      */
@@ -1280,7 +1258,14 @@ declare module '@lightningjs/blits' {
      *
      * Defaults to `0` which means no maximum
      */
-    maxFPS?: number
+    maxFPS?: number,
+    /**
+     * Custom platform layer to be used by the App (experimental)
+     *
+     * Defaults to `null` which will be resolved internally to WebPlatform
+     */
+    platform?: any
+
   }
 
   interface State {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.51.0",
+  "version": "2.0.0-beta.10",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -33,9 +33,9 @@
     "./components": "./src/components/FPScounter.js"
   },
   "scripts": {
-    "test": "c8 node scripts/runTests.js",
-    "test:ci": "c8 npm run test:run",
-    "test:run": "node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff",
+    "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",
     "lint": "node scripts/lint.js",
     "lint:fix": "node scripts/lint.js fix",
     "prepublishOnly": "node scripts/prepublishOnly.js",
@@ -71,11 +71,11 @@
     "prettier": "^3.6.2",
     "sinon": "^21.0.0",
     "tap-diff": "^0.1.1",
+    "tap-filter": "^1.0.3",
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/msdf-generator": "^1.2.0",
-    "@lightningjs/renderer": "^2.23.0",
+    "@lightningjs/renderer": "3.0.0-beta23",
     "magic-string": "^0.30.21"
   },
   "repository": {

package/scripts/lint.js

@@ -1,3 +1,20 @@
+/*
+ * 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 fg from 'fast-glob'
 import { resolve } from 'path'
 import { fileURLToPath } from 'url'

package/scripts/prepublishOnly.js

@@ -62,8 +62,8 @@ function processFile(filePath) {
   const newSource = typeof result === 'object' && result.code ? result.code : result
   fs.writeFileSync(filePath, newSource)
 
-  // only format the file if it was changed
-  if (source !== newSource) {
+  // only format the file if it was changed (compiler returns undefined for non-Blits files)
+  if (newSource !== undefined && source !== newSource) {
     formatFileWithESLint(filePath)
   }
 }

package/scripts/prepush.js

@@ -1,10 +1,6 @@
 /*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2023 Comcast
- *
- * Licensed under the Apache License, Version 2.0 (the License);
+ * 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
  *
@@ -15,6 +11,8 @@
  * 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 { execSync } from 'child_process'

package/src/component/base/methods.js

@@ -25,26 +25,14 @@ import { renderer } from '../../launch.js'
 import { keyMap } from '../../application.js'
 
 export default {
-  focus: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (e) {
-      Log.warn('this.focus is deprecated, use this.$focus instead')
-      return this.$focus(e)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $focus: {
     /**
      * @this {import('../../component').BlitsComponent}
      */
     value: function (e) {
       // force refocus when the component is already in focused state
-      if (this.lifecycle.state === 'focus') {
-        this.lifecycle.state = 'refocus'
+      if (this[symbols.lifecycle].state === 'focus') {
+        this[symbols.lifecycle].state = 'refocus'
       }
       Focus.set(this, e)
     },
@@ -92,8 +80,8 @@ export default {
      * @this {import('../../component').BlitsComponent}
      */
     value: function () {
-      this[symbols.state].hasFocus = false
-      this.lifecycle.state = 'unfocus'
+      this[symbols.state].$hasFocus = false
+      this[symbols.lifecycle].state = 'unfocus'
     },
     writable: false,
     enumerable: true,
@@ -105,11 +93,11 @@ export default {
      */
     value: function () {
       this.eol = true
-      this.lifecycle.state = 'destroy'
+      this[symbols.lifecycle].state = 'destroy'
 
       // when destroying a component that currently has focus
       // pass focus to the parent so we don't get lost in focus limbo
-      if (this.hasFocus === true) this.parent.$focus()
+      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)
@@ -142,26 +130,25 @@ export default {
       this[symbols.state] = {}
 
       this[symbols.props] = {}
-      this[symbols.computed] = null
-      this.lifecycle = {}
+      this[symbols.computedKeys] = null
+      this[symbols.lifecycle] = {}
       this[symbols.effects].length = 0
-      this.parent = null
-      this.rootParent = null
+      this[symbols.parent] = null
+      this[symbols.rootParent] = null
       this[symbols.wrapper] = null
       this[symbols.originalState] = null
       this[symbols.slots].length = 0
 
-      delete this[symbols.computed]
-      delete this.parent
-      delete this.rootParent
+      delete this[symbols.computedKeys]
+      delete this[symbols.parent]
+      delete this[symbols.rootParent]
       delete this[symbols.wrapper]
       delete this[symbols.originalState]
       delete this[symbols.children]
       delete this[symbols.slots]
-      delete this.componentId
       delete this[symbols.id]
       delete this.ref
-      delete this[symbols.state].hasFocus
+      delete this[symbols.state].$hasFocus
 
       this[symbols.holder].destroy()
       this[symbols.holder] = null
@@ -172,7 +159,8 @@ export default {
 
       delete this[symbols.effects]
 
-      Log.debug(`Destroyed component ${this.componentId}`)
+      Log.debug(`Destroyed component ${this.$componentId}`)
+      delete this.$componentId
     },
     writable: false,
     enumerable: true,
@@ -189,18 +177,6 @@ export default {
     enumerable: false,
     configurable: false,
   },
-  select: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (ref) {
-      Log.warn('this.select is deprecated, use this.$select instead')
-      return this.$select(ref)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $select: {
     /**
      * @this {import('../../component').BlitsComponent}
@@ -229,18 +205,6 @@ export default {
     enumerable: true,
     configurable: false,
   },
-  trigger: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (key) {
-      Log.warn('this.trigger is deprecated, use this.$trigger instead')
-      return this.$trigger(key)
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
   $trigger: {
     /**
      * @this {import('../../component').BlitsComponent}
@@ -262,30 +226,6 @@ export default {
     enumerable: true,
     configurable: false,
   },
-  shader: {
-    /**
-     * @this {import('../../component').BlitsComponent}
-     */
-    value: function (type, args) {
-      return {
-        type: type,
-        props: args,
-      }
-      // const shaders = renderer.driver.stage.shManager.getRegisteredEffects()
-
-      // if (target in shaders) {
-      //   return {
-      //     type: target,
-      //     props: args,
-      //   }
-      // } else {
-      //   Log.error(`Shader ${type} not found`)
-      // }
-    },
-    writable: false,
-    enumerable: true,
-    configurable: false,
-  },
 }
 
 /**

package/src/component/base/utils.js

@@ -29,6 +29,20 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  $parent: {
+    get: function () {
+      return this[symbols.parent]
+    },
+    enumerable: true,
+    configurable: false,
+  },
+  $id: {
+    get: function () {
+      return this[symbols.id]
+    },
+    enumerable: true,
+    configurable: false,
+  },
   [symbols.renderer]: {
     value: () => renderer,
     writable: false,
@@ -37,7 +51,7 @@ export default {
   },
   [symbols.getChildren]: {
     value() {
-      const parent = this.rootParent || this.parent
+      const parent = this[symbols.rootParent] || this[symbols.parent]
       return (this[symbols.children] || []).concat(
         (parent &&
           parent[symbols.getChildren]()
@@ -46,7 +60,7 @@ export default {
                 return Object.values(child).map((c) => {
                   // ugly hack .. but the point is to reference the right component
                   c.forComponent =
-                    c[Symbol.for('config')] && c[Symbol.for('config')].parent.component
+                    c[Symbol.for('config')] && c[Symbol.for('config')][symbols.parent].component
                   return c
                 })
               }
@@ -57,8 +71,8 @@ export default {
               // problem is that component of a forloop in a slot has component of root component
               if (child && child.component) {
                 return (
-                  (child.component && child.component.componentId === this.componentId) ||
-                  (child.forComponent && child.forComponent.componentId === this.componentId)
+                  (child.component && child.component.$componentId === this.$componentId) ||
+                  (child.forComponent && child.forComponent.$componentId === this.$componentId)
                 )
               }
             })) ||

package/src/component/setup/props.js

@@ -16,46 +16,55 @@
  */
 
 import { Log } from '../../lib/log.js'
-
 import symbols from '../../lib/symbols.js'
 
-const baseProp = {
-  cast: (v) => v,
-  required: false,
+const normalizeProps = (props) => {
+  Log.warn(
+    'Defining props as an Array has been deprecated and will stop working in future versions. Please use the new notation instead (an object with key values pairs).',
+    props
+  )
+  const out = {}
+  const propLength = props.length
+  for (let i = 0; i < propLength; i++) {
+    const prop = props[i]
+    if (typeof prop === 'string') {
+      out[prop] = undefined
+    } else {
+      Log.error(
+        'Defining props as an array of objects is no longer supported. Please use the new format: an object with key-value pairs.'
+      )
+      break
+    }
+  }
+  return out
 }
 
-export default (component, props = []) => {
-  if (props.indexOf('ref') === -1) {
-    props.push('ref')
+export default (component, props = {}) => {
+  if (Array.isArray(props) === true) {
+    props = normalizeProps(props)
+  }
+  if (!('ref' in props)) {
+    props.ref = undefined
   }
-  component[symbols.propKeys] = []
+  const keys = Object.keys(props)
+  component[symbols.propKeys] = keys
 
-  const propsLength = props.length
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    const defaultPropValue = props[key]
 
-  for (let i = 0; i < propsLength; i++) {
-    const prop = { ...baseProp, ...(typeof props[i] === 'object' ? props[i] : { key: props[i] }) }
-    component[symbols.propKeys].push(prop.key)
-    Object.defineProperty(component, prop.key, {
+    Object.defineProperty(component, key, {
       get() {
-        const value = prop.cast(
-          this[symbols.props] !== undefined && prop.key in this[symbols.props]
-            ? this[symbols.props][prop.key]
-            : 'default' in prop
-              ? prop.default
-              : undefined
-        )
-
-        if (prop.required === true && value === undefined) {
-          Log.warn(`${prop.key} is required`)
-        }
-
-        return value
+        if (this[symbols.props] === undefined) return undefined
+        // if the key is specified independent of the value (falsy, null, undefined) use that value
+        // otherwise return the default prop value
+        return key in this[symbols.props] ? this[symbols.props][key] : defaultPropValue
       },
       set(v) {
         Log.warn(
-          `Warning! Avoid mutating props directly (prop "${prop.key}" in component "${this.componentId}")`
+          `Warning! Avoid mutating props directly (prop "${key}" in component "${this.componentId}")`
         )
-        this[symbols.props][prop.key] = v
+        this[symbols.props][key] = v
       },
     })
   }

package/src/component/setup/state.js

@@ -28,16 +28,16 @@ export default (component, state = () => {}) => {
   })
 
   const stateKeys = Object.keys(state.apply(component) || {})
-  if (stateKeys.indexOf('hasFocus') > -1) {
+  if (stateKeys.indexOf('$hasFocus') > -1) {
     Log.warn(
-      'State `hasFocus` already exists as a built-in Component variable (to indicate whether the component currently has focus). Avoid using your own `hasFocus` key in the Component state'
+      'State `$hasFocus` already exists as a built-in Component variable (to indicate whether the component currently has focus). Avoid using your own `$hasFocus` key in the Component state'
     )
   } else {
-    // add built-in hasFocus key
-    stateKeys.push(['hasFocus'])
+    // add built-in $hasFocus key
+    stateKeys.push('$hasFocus')
   }
   // add built-in isHovered key
-  stateKeys.push(['isHovered'])
+  stateKeys.push(['$isHovered'])
   const stateKeysLength = stateKeys.length
 
   for (let i = 0; i < stateKeysLength; i++) {