@lightningjs/blits 1.11.0 → 1.13.0

package/.github/workflows/deploy-docs.yml

@@ -13,13 +13,13 @@ jobs:
       - name: Trigger Deployment
         timeout-minutes: 5
         run: |
-          response=$(curl -X POST -w "%{http_code}" -s -o /dev/null \
+          response=$(curl -X POST -d {} -H "Content-Type:application/json" -w "%{http_code}" -s -o /dev/null \
             --max-time 30 \
             --connect-timeout 10 \
             --retry 2 \
             --retry-delay 5 \
-            ${{ secrets.WEBSITE_DEPLOY_URL }})
-          if [ "$response" -eq 200 ]; then
+            "${{ secrets.WEBSITE_DEPLOY_URL }}")
+          if [ "$response" -ge 200 ] && [ "$response" -lt 300 ]; then
             echo "Deployment triggered successfully"
           else
             echo "Failed to trigger deployment. Status code: $response"

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v1.13.0
+
+_5 dec 2024_
+
+- Added `padding` attribute to Layout component
+- Added logging of Blits and Renderer version used in App
+- Fixed show attribute for elements without predefined width and height
+- Added automatic proxy fallback (when no browser support) for reactivity
+- Fixed and added tests related to Blits Element
+- Fixed memory issue with effects used in for-loop
+- Fixed memory issue when changing props in dynamic shader effects
+- Updated renderer to v2.8.0
+
+## v1.12.0
+
+_26 nov 2024_
+
+- Fixed `$hasFocus` state variable not being set when navigating back to a page with `keepAlive` enabled
+- Added `@updated`-event to Layout component
+- Fixed issue with simple config for Theme plugin
+
+
 ## v1.11.0
 
 _19 nov 2024_

package/blits.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="./index.d.ts" />
+
+declare module '*.blits' {
+  const component: any;
+  export default component;
+}

package/docs/built-in/layout.md

@@ -61,9 +61,61 @@ It's also possible to nest layouts. Simply place a new `<Layout>`-tag, with it's
 
 And of course you can nest _vertical_ Layouts inside a _horizontal_ one - and vice versa.
 
+### Padding
+
+By default a `<Layout />`-tag will be resized to the exact dimensions as the content it is containing. The `padding`-attribute can be used to add spacing between the content and the edges of the Layout Component.
+
+The `padding`-attribute accepts a `number` or an `object`. When passed a number, that padding will be applied equally to all sides. With an object value, the padding can be controlled for each side individually.
+
+Valid keys in the _padding-object_ are: `top`, `bottom`, `left`, `right`, `x` and `y`. The `x` and `y` keys can be used to define the same values for `top` and `bottom`, and `left` and `right` in one go. When a value is not specified for a side, it will default to `0`.
+
+```xml
+<Layout color="silver" padding="10" >
+  <Element w="40" h="40" color="red" />
+  <Element w="80" h="40" color="blue" />
+  <Element w="40" h="40" color="green" />
+</Layout>
+```
+
+```xml
+<Layout color="silver" padding="{x: 20, top: 30, bottom: 10}">
+  <Element w="40" h="40" color="red" />
+  <Element w="80" h="40" color="blue" />
+  <Element w="40" h="40" color="green" />
+</Layout>
+```
+
 ### Transitioning layouts
 
-The `<Layout>`-component can also take into account when dimensions of children change with a transition applied to it. The component will recalculate the position of its children as the transition progresses, making sure that elements are always perfectly positioned relative to one another.
+The `<Layout>`-component can also take into account when dimensions of children change with a transition applied to it (i.e. `<Element :w.transition="$myWidth">`). The component will recalculate the position of its children as the transition progresses, making sure that elements are always perfectly positioned relative to one another.
+
+### Updated event
+
+The `<Layout>`-tag automatically updates its dimensions based on the dimensions of its children. After each update in the children, the an `updated`-event is emitted on the `<Layout>`-tag. It will receive the current dimensions of the layout.
+
+You can tap into this event by adding an `@updated`-attribute to the `<Layout />`-tag and refer to a method in your Component logic.
+
+
+```js
+export default Blits.Component('LayoutUpdate', {
+  template: `
+    <Element>
+      <Layout @updated="$layoutUpdate">
+        <Element :w="$width" h="40" color="red" />
+        <Element :w="$width" h="40" color="blue" />
+        <Element :w="$width" h="40" color="green" />
+      </Layout>
+    </Element>
+  `,
+  methods: {
+    layoutUpdate(dimensions, el) {
+      console.log(`Layout (${el.nodeId}) dimensions updated! Width: ${dimensions.w}, Height: ${dimensions.h}`)
+    }
+  }
+})
+```
+
+> Please be aware that the `@updated` event can fire multiple times. The size of the Layout-tag is recalculated for each change in children. Also note that the `@updated` event does not guarantee a change in dimensions. It is possible that it fires for a children update, but remains the same size.
 
 ## Performance
 

package/docs/plugins/global_app_state.md

@@ -75,3 +75,24 @@ The second `$`-sign is needed, since the appState plugin itself is prefixed with
 
 In order to read or update variables on the global app state inside the component logic, you can access the entire state via `this.$appState`.
 
+### Watching global state
+
+Similar to component state, you can watch for changes in the global state as well. You can to refer to global state variables using _dot-notation_ in the watcher function name, and _prefixing_ it with `$appState`. This means that you need to define your watcher as a `String`, matching one of the examples below, depending on your style preference.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
+    </Element>
+  `,
+  watch: {
+    '$appState.fooBar'(v, old) {
+      console.log(`$appState.fooBar changed from ${old} to ${v}`)
+    },
+    '$appState.my.nested.data': function(v, old) {
+      console.log(`My nested App state data changed!`)
+    }
+  },
+})
+```

package/index.d.ts

@@ -15,6 +15,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+// blits file type reference
+/// <reference path="./blits.d.ts" />
+
 import {type ShaderEffect as RendererShaderEffect, type WebGlCoreShader} from '@lightningjs/renderer'
 
 declare module '@lightningjs/blits' {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.1.0",
-    "@lightningjs/renderer": "^2.7.1"
+    "@lightningjs/renderer": "^2.8.0"
   },
   "repository": {
     "type": "git",

package/src/component/base/methods.js

@@ -64,6 +64,14 @@ export default {
     enumerable: true,
     configurable: false,
   },
+  [symbols.removeGlobalEffects]: {
+    value: function (effects = []) {
+      removeGlobalEffects(effects)
+    },
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  },
   select: {
     value: function (ref) {
       Log.warn('this.select is deprecated, use this.$select instead')

package/src/engines/L3/element.js

@@ -22,25 +22,70 @@ import { Log } from '../../lib/log.js'
 import symbols from '../../lib/symbols.js'
 import Settings from '../../settings.js'
 
+const createPaddingObject = (padding, direction) => {
+  if (padding === undefined) {
+    return { start: 0, end: 0, oppositeStart: 0, oppositeEnd: 0 }
+  }
+
+  if (typeof padding === 'number') {
+    return { start: padding, end: padding, oppositeStart: padding, oppositeEnd: padding }
+  }
+
+  // todo: do we need to do this runtime every time? or can we optimize this?
+  if (isObjectString(padding) === true) {
+    padding = parseToObject(padding)
+  }
+
+  if (typeof padding === 'object') {
+    const {
+      top = undefined,
+      right = undefined,
+      bottom = undefined,
+      left = undefined,
+      x = 0,
+      y = 0,
+    } = padding
+
+    // use specific values if provided, otherwise fall back to x or y
+    return direction === 'vertical'
+      ? {
+          start: top !== undefined ? top : y,
+          end: bottom !== undefined ? bottom : y,
+          oppositeStart: left !== undefined ? left : x,
+          oppositeEnd: right !== undefined ? right : x,
+        }
+      : {
+          start: left !== undefined ? left : x,
+          end: right !== undefined ? right : x,
+          oppositeStart: top !== undefined ? top : y,
+          oppositeEnd: bottom !== undefined ? bottom : y,
+        }
+  }
+  return { start: 0, end: 0, oppositeStart: 0, oppositeEnd: 0 }
+}
+
 const layoutFn = function (config) {
-  let offset = 0
   const position = config.direction === 'vertical' ? 'y' : 'x'
   const oppositePosition = config.direction === 'vertical' ? 'x' : 'y'
   const oppositeMount = config.direction === 'vertical' ? 'mountX' : 'mountY'
   const dimension = config.direction === 'vertical' ? 'height' : 'width'
   const oppositeDimension = config.direction === 'vertical' ? 'width' : 'height'
+  const padding = createPaddingObject(config.padding, config.direction)
+
+  let offset = padding.start
 
-  const children = this.children
+  const children = this.node.children
   const childrenLength = children.length
   let otherDimension = 0
   const gap = config.gap || 0
   for (let i = 0; i < childrenLength; i++) {
     const node = children[i]
     node[position] = offset
+    node[oppositePosition] = padding.oppositeStart
     // todo: temporary text check, due to 1px width of empty text node
     if (dimension === 'width') {
       offset += node.width + (node.width !== ('text' in node ? 1 : 0) ? gap : 0)
-    } else if (dimension === 'height') {
+    } else {
       offset +=
         'text' in node
           ? node.width > 1
@@ -50,11 +95,14 @@ const layoutFn = function (config) {
           ? node.height + gap
           : 0
     }
-    otherDimension = Math.max(otherDimension, node[oppositeDimension])
+    otherDimension = Math.max(
+      otherDimension,
+      node[oppositeDimension] + padding.oppositeStart + padding.oppositeEnd
+    )
   }
   // adjust the size of the layout container
-  this[dimension] = offset - gap
-  this[oppositeDimension] = otherDimension
+  this.node[dimension] = offset - gap + padding.end
+  this.node[oppositeDimension] = otherDimension
 
   const align = {
     start: 0,
@@ -69,6 +117,11 @@ const layoutFn = function (config) {
       node[oppositeMount] = align
     }
   }
+
+  // emit an updated event
+  if (config['@updated'] !== undefined) {
+    config['@updated']({ w: this.node.width, h: this.node.height }, this)
+  }
 }
 
 const isTransition = (value) => {
@@ -243,8 +296,8 @@ const propsTransformer = {
   set show(v) {
     if (v) {
       this.props['alpha'] = 1
-      this.props['width'] = this.raw['w'] || this.raw['width']
-      this.props['height'] = this.raw['h'] || this.raw['height']
+      this.props['width'] = this.raw['w'] || this.raw['width'] || 0
+      this.props['height'] = this.raw['h'] || this.raw['height'] || 0
     } else {
       this.props['alpha'] = 0
       this.props['width'] = 0
@@ -267,9 +320,23 @@ const propsTransformer = {
         v[i].props.color = colors.normalize(v[i].props.color)
       }
     }
-    this.props['shader'] = renderer.createShader('DynamicShader', {
-      effects: v,
-    })
+
+    if (this.element.node === undefined) {
+      this.props['shader'] = renderer.createShader('DynamicShader', {
+        effects: v.map((effect) => {
+          return renderer.createEffect(effect.type, effect.props, effect.type)
+        }),
+      })
+    } else {
+      for (let i = 0; i < v.length; i++) {
+        const target = this.element.node.shader.props[v[i].type]
+        const props = Object.keys(v[i].props)
+
+        for (let j = 0; j < props.length; j++) {
+          target[props[j]] = v[i].props[props[j]]
+        }
+      }
+    }
   },
   set clipping(v) {
     this.props['clipping'] = v
@@ -363,7 +430,7 @@ const Element = {
     }
 
     if (props.__layout === true) {
-      this.triggerLayout = layoutFn.bind(this.node)
+      this.triggerLayout = layoutFn.bind(this)
     }
 
     if (this.config.parent.props !== undefined && this.config.parent.props.__layout === true) {

package/src/engines/L3/element.test.js

@@ -24,6 +24,8 @@ import symbols from '../../lib/symbols.js'
 
 initLog()
 
+let elementRef
+
 test('Type', (assert) => {
   assert.ok(element instanceof Function, 'Element should be a factory function')
   assert.end()
@@ -105,10 +107,98 @@ test('Element - Set `w` property', (assert) => {
   assert.end()
 })
 
+test('Element- Set `w` property in percentage', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('w', '50%')
+
+  assert.equal(el.node['width'], 960, 'Node width parameter should be set to 960')
+  assert.equal(el.props.props['width'], 960, 'Props width parameter should be set')
+  assert.equal(el.props.raw['w'], '50%', "Props' raw map entry should be added")
+
+  assert.end()
+})
+
+test('Element - Set `h` property', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('h', 100)
+
+  assert.equal(el.node['height'], 100, 'Node height parameter should be set')
+  assert.equal(el.props.props['height'], 100, 'Props height parameter should be set')
+  assert.equal(el.props.raw['h'], 100, "Props' raw map entry should be added")
+  assert.end()
+})
+
+test('Element- Set `h` property in percentage', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('h', '50%')
+
+  assert.equal(el.node['height'], 540, 'Node width parameter should be set to 540')
+  assert.equal(el.props.props['height'], 540, 'Props width parameter should be set')
+  assert.equal(el.props.raw['h'], '50%', "Props' raw map entry should be added")
+
+  assert.end()
+})
+
+test('Element - Set `x` property', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('x', 100)
+
+  assert.equal(el.node['x'], 100, 'Node x parameter should be set')
+  assert.equal(el.props.props['x'], 100, 'Props x parameter should be set')
+  assert.equal(el.props.raw['x'], 100, "Props' raw map entry should be added")
+  assert.end()
+})
+
+test('Element- Set `x` property in percentage', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('x', '50%')
+
+  assert.equal(el.node['x'], 960, 'Node x parameter should be set to 960')
+  assert.equal(el.props.props['x'], 960, 'Props x parameter should be set')
+  assert.equal(el.props.raw['x'], '50%', "Props' raw map entry should be added")
+
+  assert.end()
+})
+
+test('Element - Set `y` property', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('y', 100)
+
+  assert.equal(el.node['y'], 100, 'Node y parameter should be set')
+  assert.equal(el.props.props['y'], 100, 'Props y parameter should be set')
+  assert.equal(el.props.raw['y'], 100, "Props' raw map entry should be added")
+  assert.end()
+})
+
+test('Element- Set `y` property in percentage', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('y', '50%')
+
+  assert.equal(el.node['y'], 540, 'Node y parameter should be set to 540')
+  assert.equal(el.props.props['y'], 540, 'Props y parameter should be set')
+  assert.equal(el.props.raw['y'], '50%', "Props' raw map entry should be added")
+
+  assert.end()
+})
+
 test('Element - Set `mount` property', (assert) => {
   assert.capture(renderer, 'createNode', () => new EventEmitter())
   const el = createElement()
-  const value = { x: 10, y: 20 }
+  const value = '{ x: 10, y: 20 }'
 
   el.set('mount', value)
 
@@ -271,8 +361,87 @@ test('Element - Set `fit` property should not set not required keys', (assert) =
   )
   assert.end()
 })
+
+test('Element - Set `float` property with value `center`', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('float', 'center')
+
+  assert.equal(el.node['mountX'], 0.5, 'Node mountX parameter should set to 0.5')
+  assert.equal(el.props.props['mountX'], 0.5, 'Props mountX parameter should set to 0.5')
+  assert.equal(el.node['x'], 960, 'Node x parameter should set to half of parent node width, 960')
+  assert.equal(el.props.props['x'], 960, 'props x parameter should be set to 960')
+
+  assert.end()
+})
+
+test('Element - Set `float` property with value `right`', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('float', 'right')
+
+  assert.equal(el.node['mountX'], 1, 'Node mountX parameter should set to 1')
+  assert.equal(el.props.props['mountX'], 1, 'Props mountX parameter should set to 1')
+  assert.equal(el.node['x'], 1920, 'Node x parameter should set to parent node full width, 1920')
+  assert.equal(el.props.props['x'], 1920, 'props x parameter should be set to 1920')
+
+  assert.end()
+})
+
+test('Element - Set `float` property with value `unknown`', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('float', 'unknown')
+
+  assert.equal(el.node['mountX'], undefined, 'Node mountX parameter should not be changed')
+  assert.equal(el.props.props['mountX'], undefined, 'Props mountX parameter should not be changed')
+  assert.equal(el.node['x'], undefined, 'Node x parameter should not get updated')
+  assert.equal(el.props.props['x'], undefined, 'props x parameter should not be changed')
+
+  assert.end()
+})
+
+test('Element - Set `show` property as false', (assert) => {
+  assert.capture(renderer, 'createNode', () => new EventEmitter())
+  const el = createElement()
+
+  el.set('w', 960)
+  el.set('h', 540)
+
+  el.set('show', false)
+
+  elementRef = el
+
+  assert.equal(el.node['alpha'], 0, 'Node alpha parameter should set to 0')
+  assert.equal(el.props.props['alpha'], 0, 'Props alpha parameter should set')
+  assert.equal(el.node['width'], 0, 'Node width parameter should set to 0')
+  assert.equal(el.props.props['width'], 0, 'props width parameter should set to 0')
+  assert.equal(el.node['height'], 0, 'Node height parameter should set to 0')
+  assert.equal(el.props.props['height'], 0, 'props height parameter should set to 0')
+
+  assert.end()
+})
+
+test('Element - Set `show` property as false', (assert) => {
+  const el = elementRef
+
+  el.set('show', true)
+
+  assert.equal(el.node['alpha'], 1, 'Node alpha parameter should be set')
+  assert.equal(el.props.props['alpha'], 1, 'Props alpha parameter should be set')
+  assert.equal(el.node['width'], 960, 'Node width parameter should be set')
+  assert.equal(el.props.props['width'], 960, 'props width parameter should be set')
+  assert.equal(el.node['height'], 540, 'Node height parameter should be set')
+  assert.equal(el.props.props['height'], 540, 'props height parameter should be set')
+
+  assert.end()
+})
+
 function createElement() {
-  const el = element({}, {})
+  const el = element({ parent: { node: { width: 1920, height: 1080 } } }, {})
   el.populate({
     parent: {
       node: new EventEmitter(),

package/src/launch.js

@@ -16,8 +16,9 @@
  */
 
 import Settings from './settings.js'
-import { initLog } from './lib/log.js'
+import { initLog, Log } from './lib/log.js'
 import engine from './engine.js'
+import packageInfo from '../package.json'
 
 export let renderer = {}
 export const stage = {}
@@ -26,6 +27,8 @@ export default (App, target, settings) => {
   Settings.set(settings)
 
   initLog()
+  Log.info('Blits Version ', packageInfo.version)
+  Log.info('Renderer Version ', packageInfo.dependencies['@lightningjs/renderer'])
 
   stage.element = engine.Element
 

package/src/lib/codegenerator/generator.js

@@ -337,6 +337,7 @@ const generateForLoopCode = function (templateObject, parent) {
   ctx.renderCode.push(`
       created.length = 0
       const length = rawCollection.length
+      const effects = []
       for(let __index = 0; __index < length; __index++) {
         const scope = Object.create(component)
         parent = ${parent}
@@ -405,7 +406,7 @@ const generateForLoopCode = function (templateObject, parent) {
           ${effect}
         }
         effect(eff${index}, ${key})
-        component[Symbol.for('effects')].push(eff${index})
+        effects.push(eff${index})
       `)
     } else {
       // props shouldn't be wrapped in an effect, but simply passed on
@@ -416,6 +417,7 @@ const generateForLoopCode = function (templateObject, parent) {
   })
   ctx.renderCode.push(`
     }
+    return effects
   }`)
 
   // generate code that destroys items
@@ -436,7 +438,7 @@ const generateForLoopCode = function (templateObject, parent) {
       `)
   }
   destroyCode.push(`
-       }
+      }
     }
   `)
 
@@ -451,8 +453,14 @@ const generateForLoopCode = function (templateObject, parent) {
   }
 
   ctx.renderCode.push(`
+    let forEffects${forStartCounter}
     effect(() => {
-      forloop${forStartCounter}(${cast(result[2], ':for')}, elms, created${forStartCounter})
+      component[Symbol.for('removeGlobalEffects')](forEffects${forStartCounter})
+      forEffects${forStartCounter} = null
+      forEffects${forStartCounter} = forloop${forStartCounter}(${cast(
+    result[2],
+    ':for'
+  )}, elms, created${forStartCounter})
     }, '${effectKey}' )
   `)
 

package/src/lib/reactivity/reactive.js

@@ -164,7 +164,13 @@ const reactiveDefineProperty = (target, global) => {
   return target
 }
 
+const hasProxySupport = typeof Proxy !== 'undefined'
+
 export const reactive = (target, mode = 'Proxy', global = false) => {
+  // force defineProperty reactivity mode when no proxy support
+  if (hasProxySupport === false) {
+    mode = 'defineProperty'
+  }
   return mode === 'defineProperty'
     ? reactiveDefineProperty(target, global)
     : reactiveProxy(target, undefined, undefined, global)

package/src/lib/symbols.js

@@ -48,4 +48,6 @@ export default {
   isComponent: Symbol.for('isComponent'),
   // Symbol 'effects' utilized within generated code
   effects: Symbol.for('effects'),
+  // Symbol 'removeGlobalEffects' utilized within generated code
+  removeGlobalEffects: Symbol.for('removeGlobalEffects'),
 }

package/src/plugins/theme.js

@@ -72,7 +72,7 @@ export default {
         // theme get function when current theme is modified
         state.current
         if (themeMap[key] !== undefined) return themeMap[key]
-        const value = getValueByDotNotation(themes[state.current], themes[base], key)
+        const value = getValueByDotNotation(themes[state.current], themes[base] || null, key)
         if (value !== undefined) {
           // store the value for next time
           themeMap[key] = value

package/src/router/router.js

@@ -195,7 +195,7 @@ export const navigate = async function () {
       previousFocus = Focus.get()
 
       // set focus to the view that we're routing to
-      focus ? Focus.set(focus) : Focus.set(view)
+      focus ? focus.$focus() : view.$focus()
 
       // apply before settings to holder element
       if (route.transition.before) {