@lightningjs/blits 0.8.1 → 0.9.1

package/docs/transitions_animations/transitions.md

@@ -0,0 +1,132 @@
+# Blits - Lightning 3 App Development Framework
+
+## Transitions
+
+So far we have explored how to create components and draw elements on the screen. But everything has
+been rather static so far.
+
+We did learn how to _reactively_ changes values and trigger rerenders based on that. So if you try the example below, you'll see that indeed our golden element changes position. But it just jumps from one place to another:
+
+```js
+export default Blits('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100" :x="$x" :y=:"$y" />
+  `,
+  state() {
+    return {
+      x: 0,
+      y: 0,
+    }
+  },
+  input: {
+    enter() {
+      this.x = this.x + 100
+      this.y = this.y + 50
+    }
+  },
+```
+
+Using _transitions_ we really make our App come alive.
+
+### Applying a transition
+
+Blits offers an easy and intuitive way to apply transitions. All you need to do is add the `.transition` modifier to a reactive attribute, and now whenever you change the value referenced in the attribute, it will automatically _smooth_ into the new value.
+
+```js
+export default Blits('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100" :x.transiton="$x" :y.transition=:"$y" />
+  `,
+  state() {
+    return {
+      x: 0,
+      y: 0,
+    }
+  },
+  input: {
+    enter() {
+      this.x = this.x + 100
+      this.y = this.y + 50
+    }
+  },
+```
+
+If we try out the modified example above, you'll notice how difference adding a simple transition makes.
+
+When the `.transition`-modifier is added to a reactive attribute, a default `ease-in` transition with a duration of `300ms` is applied
+
+### Customizing transitions
+
+While the default transition will look pretty good out of the box and is great for quickly improving the look of your App, you may want to customize specific transitions.
+
+Blits gives you full control over your transitions, with a simple to use format, right inside your template.
+
+Instead of referencing your component's state variable directly, you can also supply an inlien `object literal` in the attribute with a `.transition`-modifier. This will allow you to pass a number of options to change the way the transition will work.
+
+The transition object must have a `value` key, which references the state variable (or prop or computed property) that triggers the transition.
+
+Further more you can specify:
+
+- `duration` - the duration of the transition in `ms`
+- `delay` - the time in `ms` after which the transition should initiate
+- `easing` - the easing function of the transition. Can be one of the defaults easing options listed below, or a custom `cubic-bezier` definitions (i.e. `cubic-bezier(0,1.35,.99,-0.07)`).
+
+```xml
+<Element color="gold" w="100" h="100"
+  :x.transiton="{value: $x, duration: 300, easing: 'ease-in-back', delay: 400}"
+  :y.transition=:"{value: $x, duration: 300, easing: 'cubic-bezier(1,-0.64,0.39,1.44)'}">
+</Element>
+```
+
+Besides a reference to the `value`, you can also use dynamic values for the other keys in the transition object. This way you'll be able to dynamically control the delay, duration or easing function.
+
+```xml
+<Element color="gold" w="100" h="100"
+  :x.transiton="{value: $x, duration: $dynamicDuration, delay: $dynamicDelay}">
+</Element>
+```
+
+#### Available easing functions
+
+- `ease-in`
+- `ease-out`
+- `ease-in-out`
+- `ease-in-sine`
+- `ease-out-sine`
+- `ease-in-out-sine`
+- `ease-in-cubic`
+- `ease-out-cubic`
+- `ease-in-out-cubic`
+- `ease-in-circ`
+- `ease-out-circ`
+- `ease-in-out-circ`
+- `ease-in-back`
+- `ease-out-back`
+- `ease-in-out-back`
+
+### Listening to transition events
+
+Sometimes you may want to perform an action when a transition ends or when it starts.
+
+You can easily hook into these transiti)on events by adding a `start` and `end` key to the transition object. Both value should be a function (or a reference to a `method` on your component).
+
+The `start` function will be called when the transition actually starts (after a possible specified delay) and the `end` function is called as soon as the transitions is finished.
+
+```js
+export default Blits('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100"
+      :x.transiton="{value: $x, start: $transitionBegin, end: $transitionEnd}"
+    />
+  `,
+  ///
+  methods: {
+    transitionBegin() {
+      //
+    },
+    transitionEnd() {
+      //
+    },
+  }
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -45,7 +45,7 @@
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "^0.7.5",
+    "@lightningjs/renderer": "^0.7.6",
     "@lightningjs/vite-plugin-import-chunk-url": "^0.3.0",
     "execa": "^8.0.1",
     "kolorist": "^1.8.0",

package/src/component.js

@@ -40,6 +40,8 @@ import lifecycle from './lib/lifecycle.js'
 import Settings from './settings.js'
 import symbols from './lib/symbols.js'
 
+let counter = 0
+
 const stage = {
   element,
 }
@@ -56,10 +58,12 @@ const Component = (name = required('name'), config = required('config')) => {
       config.code = codegenerator.call(config, parser(config.template, name, parentComponent))
     }
 
+    component[symbols.identifier] = ++counter
+
     setupBase(component, name)
 
     // setup hooks
-    registerHooks(config.hooks, name)
+    registerHooks(config.hooks, component[symbols.identifier])
 
     // setup props
     // if (config.props) // because of the default props like id - might change this
@@ -97,7 +101,9 @@ const Component = (name = required('name'), config = required('config')) => {
       setupComponent(parentComponent)
     }
     if (config.hooks && config.hooks.frameTick) {
-      renderer.on('frameTick', (r, data) => emit('frameTick', name, this, [data]))
+      renderer.on('frameTick', (r, data) =>
+        emit('frameTick', component[symbols.identifier], this, [data])
+      )
     }
 
     this.parent = parentComponent
@@ -137,7 +143,10 @@ const Component = (name = required('name'), config = required('config')) => {
     })
 
     Object.defineProperty(this, symbols.originalState, {
-      value: (config.state && typeof config.state === 'function' && config.state.apply(this)) || {},
+      value: {
+        ...((config.state && typeof config.state === 'function' && config.state.apply(this)) || {}),
+        ...{ hasFocus: false },
+      },
       writable: false,
       enumerable: false,
       configurable: false,

package/src/element.js

@@ -194,7 +194,7 @@ const Props = {
     this._set.add('alpha')
   },
   set text(v) {
-    this._props.text = v !== undefined ? v.toString() : ''
+    this._props.text = v.toString()
   },
   set effects(v) {
     this._props.shader = renderer.createShader('DynamicShader', {
@@ -229,7 +229,7 @@ const Props = {
     this._props.overflowSuffix = v === false ? ' ' : v === true ? undefined : v
   },
   set letterSpacing(v) {
-    this._props.letterSpacing = v
+    this._props.letterSpacing = v || 1
   },
   set lineHeight(v) {
     this._props.lineHeight = v
@@ -259,12 +259,14 @@ const Element = {
     for (const [prop, value] of Object.entries(props)) {
       const descriptor = Object.getOwnPropertyDescriptor(Props, prop)
       if (descriptor && descriptor.set) {
-        this.props[prop] = unpackTransition(value)
+        if (value !== undefined) {
+          this.props[prop] = unpackTransition(value)
+        }
       }
     }
 
-    // correct for default white nodes
-    if (!this.props._set.has('color')) {
+    // correct for default white nodes (but not for text nodes)
+    if (!props.__textnode && !this.props._set.has('color')) {
       this.props._props.color =
         this.props._set.has('src') || this.props._set.has('texture') ? 0xffffffff : 0
     }
@@ -286,6 +288,7 @@ const Element = {
     }
   },
   set(prop, value) {
+    if (value === undefined) return
     const propsSet = new Set(this.props._set)
 
     this.props._props = {}

package/src/fontLoader.js

@@ -1,26 +1,25 @@
-import { CoreExtension, WebTrFontFace, SdfTrFontFace } from '@lightningjs/renderer/core'
+import { WebTrFontFace, SdfTrFontFace } from '@lightningjs/renderer/core'
 
 import Settings from './settings'
+import { renderer } from './launch'
 
-export default class FontLoader extends CoreExtension {
-  async run(stage) {
-    Settings.get('fonts', []).forEach((font) => {
-      if (font.type === 'sdf' || font.type === 'msdf') {
-        // automatically map png key to file name
-        if (!font.png && font.file) {
-          font.png = font.file.replace(/\.[^.]+$/, `.${font.type}.png`)
-        }
-        // automatically map json to file name
-        if (!font.json && font.file) {
-          font.json = font.file.replace(/\.[^.]+$/, `.${font.type}.json`)
-        }
-
-        stage.fontManager.addFontFace(
-          new SdfTrFontFace(font.family, {}, font.type, stage, font.png, font.json)
-        )
-      } else if (font.type === 'web') {
-        stage.fontManager.addFontFace(new WebTrFontFace(font.family, {}, font.file))
+export default () => {
+  const stage = renderer.driver.stage
+  Settings.get('fonts', []).forEach((font) => {
+    if (font.type === 'sdf' || font.type === 'msdf') {
+      // automatically map png key to file name
+      if (!font.png && font.file) {
+        font.png = font.file.replace(/\.[^.]+$/, `.${font.type}.png`)
+      }
+      // automatically map json to file name
+      if (!font.json && font.file) {
+        font.json = font.file.replace(/\.[^.]+$/, `.${font.type}.json`)
       }
-    })
-  }
+      stage.fontManager.addFontFace(
+        new SdfTrFontFace(font.family, {}, font.type, stage, font.png, font.json)
+      )
+    } else if (font.type === 'web') {
+      stage.fontManager.addFontFace(new WebTrFontFace(font.family, {}, font.file))
+    }
+  })
 }

package/src/launch.d.ts

@@ -16,7 +16,7 @@
  */
 
 import ApplicationInstance from './application'
-
+import {type Stage} from '@lightningjs/renderer'
 interface WebFont {
   /**
   * Name of the font family
@@ -70,6 +70,9 @@ export type DebugLevel = 0 | 1 | 2
 export type LogTypes = 'info' | 'warn' | 'error' | 'debug'
 export type ReactivityModes = 'Proxy' | 'defineProperty'
 
+interface ExtensionLoader {
+  async (stage: Stage): void
+}
 /**
  * Settings
  *
@@ -92,11 +95,7 @@ export interface Settings {
   /**
    * Debug level for console log messages
    */
-  debugLevel?: DebugLevel | LogTypes[]
-  /**
-   * Font loader file
-   */
-  fontLoader?: any
+  debugLevel?: DebugLevel | LogTypes[],
   /**
    * Fonts to be used in the Application
    */
@@ -191,7 +190,23 @@ export interface Settings {
    *
    * Defaults to `false`
    */
-  inspector?: boolean
+  inspector?: boolean,
+  /**
+   * Add an extra margin to the viewport for earlier pre-loading of elements and components
+   *
+   * By default the Lightning renderer, only renders elements that are inside the defined viewport.
+   * Everything outside of these bounds is removed from the render tree.
+   *
+   * With the viewportMargin you have the option to _virtually_ increase the viewport area,
+   * to expedite the pre-loading of elements and / or delay the unloading of elements depending
+   * on their position in the (virtual) viewport
+   *
+   * The margin can be specified in 4 directions by defining an array [top, right, bottom, left],
+   * or as a single number which is then applied to all 4 directions equally.
+   *
+   * Defaults to `0`
+   */
+  viewportMargin?: number | [number, number, number, number]
 }
 
 /**

package/src/launch.js

@@ -21,6 +21,7 @@ import Settings from './settings.js'
 import { initLog, Log } from './lib/log.js'
 import { screenResolutions } from './lib/utils.js'
 import colors from './lib/colors/colors.js'
+import fontLoader from './fontLoader.js'
 
 export let renderer
 
@@ -36,11 +37,20 @@ export default (App, target, settings) => {
   //     })
   //   : new MainCoreDriver()
 
+  if ('fontLoader' in settings) {
+    Log.warn(
+      `
+
+Starting version 0.9.0 of Blits, the Launch setting \`fontLoader\` is not supported / required anymore.
+You can remove the option from your \`src/index.js\`-file. And you can safely remove the file \`src/fontLoader.js\` from your project.
+      `
+    )
+  }
+
   renderer = new RendererMain(
     {
       appWidth: settings.w || 1920,
       appHeight: settings.h || 1080,
-      coreExtensionModule: settings.fontLoader,
       fpsUpdateInterval: settings.fpsInterval || 1000,
       deviceLogicalPixelRatio:
         settings.pixelRatio ||
@@ -53,6 +63,7 @@ export default (App, target, settings) => {
           : window.navigator.hardwareConcurrency || 2,
       clearColor: (settings.canvasColor && colors.normalize(settings.canvasColor)) || 0x00000000,
       enableInspector: settings.inspector || false,
+      boundsMargin: settings.viewportMargin || 0,
     },
     target,
     driver
@@ -68,5 +79,5 @@ export default (App, target, settings) => {
     }
   }
 
-  renderer.init().then(() => initApp())
+  renderer.init().then(fontLoader).then(initApp)
 }

package/src/lib/codegenerator/generator.js

@@ -216,6 +216,8 @@ const generateForLoopCode = function (templateObject, parent) {
   if (parent) {
     ctx.renderCode.push(`parent = ${parent}`)
   }
+
+  const forCounter = counter
   ctx.renderCode.push(`
     const collection = ${cast(result[2], ':for')}
     const keys = []
@@ -223,7 +225,7 @@ const generateForLoopCode = function (templateObject, parent) {
       parent = ${parent}
       if(!component.key) keys.length = 0
       const scope = Object.assign(component, {
-        key: Math.random(),
+        key: Math.random().toString(),
         ${index}: __index,
         ${item}: collection[__index],
     `)
@@ -241,7 +243,7 @@ const generateForLoopCode = function (templateObject, parent) {
 
   if ('key' in templateObject) {
     ctx.renderCode.push(`
-      keys.push(${interpolate(templateObject.key, 'scope.')})
+      keys.push(${interpolate(templateObject.key, 'scope.')}.toString())
     `)
   } else {
     ctx.renderCode.push(`
@@ -269,12 +271,11 @@ const generateForLoopCode = function (templateObject, parent) {
   ctx.renderCode.push('}')
 
   ctx.renderCode.push(`
-    if(elms[${counter}]) {
-      Object.keys(elms[${counter}]).forEach(key => {
+   if(elms[${forCounter}]) {
+      Object.keys(elms[${forCounter}]).forEach(key => {
         if(keys.indexOf(key) === -1) {
-          elms[${counter}][key].delete && elms[${counter}][key].delete()
-          elms[${counter}][key].destroy && elms[${counter}][key].destroy()
-          delete elms[${counter}][key]
+          elms[${forCounter}][key].destroy && elms[${forCounter}][key].destroy()
+          delete elms[1][key]
         }
       })
     }

package/src/lib/codegenerator/generator.test.js

@@ -2145,7 +2145,6 @@ test('Generate code for a template with a simple for-loop on an Element', (asser
       if(elms[1]) {
         Object.keys(elms[1]).forEach(key => {
           if(keys.indexOf(key) === -1) {
-            elms[1][key].delete && elms[1][key].delete()
             elms[1][key].destroy && elms[1][key].destroy()
             delete elms[1][key]
           }
@@ -2237,7 +2236,6 @@ test('Generate code for a template with a simple for-loop on an Element with a c
       if(elms[1]) {
         Object.keys(elms[1]).forEach(key => {
           if(keys.indexOf(key) === -1) {
-            elms[1][key].delete && elms[1][key].delete()
             elms[1][key].destroy && elms[1][key].destroy()
             delete elms[1][key]
           }
@@ -2314,25 +2312,24 @@ test('Generate code for a template with a simple for-loop on an Element with a k
           index: __index,
           item: collection[__index],
         })
-        keys.push(item.id)
+        keys.push(scope.item.id)
 
         parent = elms[0]
         elms[1] = elms[1] || {}
-        if(!elms[1][item.id]) {
-          elms[1][item.id] = this.element({parent: parent || 'root'}, component)
+        if(!elms[1][scope.item.id]) {
+          elms[1][scope.item.id] = this.element({parent: parent || 'root'}, component)
         }
 
         const elementConfig1 = {}
-        elementConfig1['key'] = "item.id"
+        elementConfig1['key'] = scope.item.id
 
-        if(!elms[1][item.id].nodeId) {
-          elms[1][item.id].populate(elementConfig1)
+        if(!elms[1][scope.item.id].nodeId) {
+          elms[1][scope.item.id].populate(elementConfig1)
         }
       }
       if(elms[1]) {
         Object.keys(elms[1]).forEach(key => {
           if(keys.indexOf(key) === -1) {
-            elms[1][key].delete && elms[1][key].delete()
             elms[1][key].destroy && elms[1][key].destroy()
             delete elms[1][key]
           }
@@ -2424,7 +2421,7 @@ test('Generate code for a template with a simple for-loop on a Component with a
 
         if(typeof cmp1 !== 'undefined') {
           for(let key in cmp1.config.props) {
-            delete  elementConfig1[cmp1.config.props[key]]
+            delete elementConfig1[cmp1.config.props[key]]
           }
         }
 
@@ -2449,12 +2446,11 @@ test('Generate code for a template with a simple for-loop on a Component with a
           }
         }
       }
-      if(elms[2]) {
-        Object.keys(elms[2]).forEach(key => {
+      if(elms[1]) {
+        Object.keys(elms[1]).forEach(key => {
           if(keys.indexOf(key) === -1) {
-            elms[2][key].delete && elms[2][key].delete()
-            elms[2][key].destroy && elms[2][key].destroy()
-            delete elms[2][key]
+            elms[1][key].destroy && elms[1][key].destroy()
+            delete elms[1][key]
           }
         })
       }
@@ -2550,7 +2546,6 @@ test('Generate code for a template with a simple for-loop on an Element with an
       if(elms[1]) {
         Object.keys(elms[1]).forEach(key => {
           if(keys.indexOf(key) === -1) {
-            elms[1][key].delete && elms[1][key].delete()
             elms[1][key].destroy && elms[1][key].destroy()
             delete elms[1][key]
           }

package/src/lib/hooks.js

@@ -19,20 +19,20 @@ import symbols from './symbols.js'
 
 const cbs = {}
 
-export const emit = (hook, name, scope, data = []) => {
-  cbs[name] && cbs[name][hook] && cbs[name][hook].apply(scope, data)
+export const emit = (hook, identifier, scope, data = []) => {
+  cbs[identifier] && cbs[identifier][hook] && cbs[identifier][hook].apply(scope, data)
 }
 
-export const privateEmit = (hook, name, scope) => {
+export const privateEmit = (hook, identifier, scope) => {
   const symHook = symbols[hook]
-  cbs[name] && cbs[name][symHook] && cbs[name][symHook].apply(scope)
+  cbs[identifier] && cbs[identifier][symHook] && cbs[identifier][symHook].apply(scope)
 }
 
-export const registerHooks = (hooks = {}, name) => {
-  cbs[name] = {}
+export const registerHooks = (hooks = {}, identifier) => {
+  cbs[identifier] = {}
   // Combines enumerable keys and symbol properties of the 'hooks' object
   const hookKeys = [...Object.keys(hooks), ...Object.getOwnPropertySymbols(hooks)]
   hookKeys.forEach((hook) => {
-    if (typeof hooks[hook] === 'function') cbs[name][hook] = hooks[hook]
+    if (typeof hooks[hook] === 'function') cbs[identifier][hook] = hooks[hook]
   })
 }

package/src/lib/lifecycle.js

@@ -17,6 +17,7 @@
 
 import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
+import symbols from './symbols.js'
 
 const states = ['init', 'ready', 'focus', 'unfocus', 'destroy']
 
@@ -34,9 +35,9 @@ export default {
       this.previous = this.current
       this.current = v
       // emit 'private' hook
-      privateEmit(v, this.component.name, this.component)
+      privateEmit(v, this.component[symbols.identifier], this.component)
       // emit 'public' hook
-      emit(v, this.component.name, this.component)
+      emit(v, this.component[symbols.identifier], this.component)
     }
   },
 }

package/src/lib/reactivity/effect.js

@@ -16,10 +16,33 @@
  */
 
 let currentEffect = null
+
+let paused = false
+
+export const pauseTracking = () => {
+  paused = true
+}
+
+export const resumeTracking = () => {
+  paused = false
+  for (let i = 0; i < trackQueue.length; i++) {
+    const item = trackQueue[i]
+    currentEffect = item.currentEffect
+    track(item.target, item.key)
+  }
+  trackQueue.length = 0
+}
+
 const objectMap = new WeakMap()
 
+const trackQueue = []
+
 export const track = (target, key) => {
   if (currentEffect) {
+    if (paused) {
+      trackQueue.push({ target, key, currentEffect })
+      return
+    }
     let effectsMap = objectMap.get(target)
     if (!effectsMap) {
       effectsMap = new Map()