@lightningjs/blits 0.3.15 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+# v0.4.1
+
+_13 nov 2023_
+
+- Added support for using dynamic import of components in routes
+- Added support for returning components in an async function / Promise in routes
+
+## v0.4.0
+
+_9 nov 2023_
+
+- Fixed bug related to animating percentage based values
+- Added (customizable) navigation transitions to the router
+- Renamed `.eslintrc.js` to `.eslintrc.cjs` in boilerplate code to make linting work on new projects
+- Fixed issue in Settings when the default value was set to `false`
+- Replace underscored keys for private properties with Symbols
+- Added `keepAlive` option to the router (i.e. keeping a page in memory when navigating to a new page)
+- Introduced a `this.$trigger` function to force a reevaluation of a reactive value (without changing the value)
+- Exposed `currentRoute`, `routes` and `navigating` on the `this.$router` object
+- Upgraded to lates version of `@lightningjs/renderer` (v0.5.0)
+
 ## v0.3.15
 
 _23 oct 2023_

package/README.md

@@ -20,8 +20,14 @@ Firstly, it's short, memorable and just has a nice ring to it.
 
 Finally it's a nerdy reference to the computer term "Bit Blits" commonly used in graphics processing, for rapidly moving a block of data into memory - quite similar to what Lightning is doing 🙂
 
+## Documentation
+
 Check out the [documentation](https://lightning-js.github.io/blits) to learn more.
 
+## Examples
+
+Check out the open source [Demo/Example app](https://github.com/lightning-js/blits-example-app) to see what Blits and Lightning are capable of and learn how to use Blits by example.
+
 ## Changelog
 
 The full Changelog can be found [here](./CHANGELOG.md)

package/boilerplate/package.json

@@ -31,6 +31,6 @@
     "vite": "^4.0.4"
   },
   "dependencies": {
-    "@lightningjs/blits": "^0.3.15"
+    "@lightningjs/blits": "^0.4.1"
   }
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.3.15",
+  "version": "0.4.1",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.cjs",
   "exports": {
     ".": "./index.js",
     "./vite": "./vite/index.js",
-    "./fontloader": "./src/fontLoader.js"
+    "./fontloader": "./src/fontLoader.js",
+    "./transitions": "./src/router/transitions/index.js"
   },
   "scripts": {
     "test": "c8 npm run test:run",
@@ -41,7 +42,7 @@
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "^0.4.0",
+    "@lightningjs/renderer": "^0.5.0",
     "@lightningjs/vite-plugin-import-chunk-url": "^0.3.0"
   }
 }

package/src/application.d.ts

@@ -19,7 +19,66 @@ import {default as Component, ComponentInstance} from './component'
 
 declare namespace Application {
 
-  interface Route {
+  interface Transition {
+    /**
+     * Name of the prop to transition (i.e. 'x', 'y', 'alpha', 'color')
+     */
+    prop: string,
+    /**
+     * Value the prop should transition to (i.e. 0, 100, '#223388')
+     */
+    value: any,
+    /**
+     * Duration of the transition in milliseconds, defaults to 300
+     */
+    duration?: number,
+    /**
+     * Easing function to apply to the transition
+     */
+    function?: string,
+    /**
+     * Delay before the transition starts in milliseconds
+     */
+    delay?: number
+  }
+
+  interface Before {
+    /**
+    * Name of the prop to set before the transition starts
+    */
+    prop: string,
+    /**
+     * Value the prop to set before the transition starts
+     */
+    value: any,
+  }
+
+  interface RouteTransition {
+    /**
+     * Setting or Array of Settings before new view enters into the router view
+     */
+    before: Before | Before[],
+    /**
+     * Transition or Array of Transitions for new view to enters into the router view
+     */
+    in: Transition | Transition[],
+    /**
+     * Transition or Array of Transitions for old view to leave the router view
+     */
+    out: Transition | Transition[],
+  }
+
+  type RouteTransitionFunction = (previousRoute: Route, currentRoute: Route) => RequireAtLeastOne<RouteTransition>
+
+  function Application(
+    config: Application.ApplicationConfig
+  ) : Application.ApplicationInstance
+
+  type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
+  }[keyof T]
+
+  type Route = {
     /**
      * URI path for the route
      */
@@ -27,7 +86,15 @@ declare namespace Application {
     /**
      * Component to load when activating the route
      */
-    component: typeof ComponentInstance
+    component: typeof ComponentInstance,
+    /**
+     * Transition configuration for the route
+     */
+    transition?: RequireAtLeastOne<RouteTransition> | RouteTransitionFunction,
+    /**
+     * Extra route options
+     */
+    options?: object // todo: specify which options are available
   }
 
   export interface ApplicationInstance extends ComponentInstance {}
@@ -46,7 +113,7 @@ declare namespace Application {
      * ]
      * ```
      */
-    routes: Route[]
+    routes?: Route[]
   }
 }
 

package/src/application.js

@@ -19,6 +19,8 @@ import Component from './component.js'
 import Focus from './focus.js'
 import Settings from './settings.js'
 
+import symbols from './lib/symbols.js'
+
 const Application = (config) => {
   const defaultKeyMap = {
     ArrowLeft: 'left',
@@ -43,11 +45,11 @@ const Application = (config) => {
 
   let handler
 
-  config.hooks.___destroy = function () {
+  config.hooks[symbols.destroy] = function () {
     document.removeEventListener('keydown', handler)
   }
 
-  config.hooks.___init = function () {
+  config.hooks[symbols.init] = function () {
     const keyMap = { ...defaultKeyMap, ...Settings.get('keymap', {}) }
 
     handler = (e) => {
@@ -57,7 +59,8 @@ const Application = (config) => {
 
     document.addEventListener('keydown', handler)
 
-    Focus.set(this)
+    // next tick
+    setTimeout(() => Focus.set(this))
   }
 
   const App = Component('App', config)

package/src/component.js

@@ -21,7 +21,7 @@ import codegenerator from './lib/codegenerator/generator.js'
 import element from './element.js'
 
 import { createHumanReadableId, createInternalId } from './lib/componentId.js'
-import { registerHooks, emit } from './lib/hooks.js'
+import { registerHooks, emit, privateEmit } from './lib/hooks.js'
 
 import { reactive } from './lib/reactivity/reactive.js'
 import setupBase from './lib/setup/base.js'
@@ -35,6 +35,8 @@ import setupWatch from './lib/setup/watch.js'
 import { effect } from './lib/reactivity/effect.js'
 import { Log } from './lib/log.js'
 
+import symbols from './lib/symbols.js'
+
 const stage = {
   element,
 }
@@ -101,7 +103,7 @@ const Component = (name = required('name'), config = required('config')) => {
           )
           this.previous = this.current
           // emit 'private' hook
-          emit(`___${v}`, name, scope)
+          privateEmit(v, name, scope)
           // emit 'public' hook
           emit(v, name, scope)
           this.current = v
@@ -118,6 +120,7 @@ const Component = (name = required('name'), config = required('config')) => {
     }
 
     this.parent = parentComponent
+    this.wrapper = parentEl
 
     Object.defineProperties(this, {
       type: {
@@ -132,13 +135,13 @@ const Component = (name = required('name'), config = required('config')) => {
         enumerable: true,
         configurable: false,
       },
-      ___id: {
+      [symbols.id]: {
         value: createInternalId(),
         writable: false,
         enumerable: false,
         configurable: false,
       },
-      ___props: {
+      [symbols.props]: {
         value: reactive(opts.props || {}),
         writable: false,
         enumerable: false,
@@ -146,10 +149,15 @@ const Component = (name = required('name'), config = required('config')) => {
       },
     })
 
-    Object.defineProperty(this, '___state', {
-      value: reactive(
-        (config.state && typeof config.state === 'function' && config.state.apply(this)) || {}
-      ),
+    Object.defineProperty(this, symbols.originalState, {
+      value: (config.state && typeof config.state === 'function' && config.state.apply(this)) || {},
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    })
+
+    Object.defineProperty(this, symbols.state, {
+      value: reactive(this[symbols.originalState]),
       writable: false,
       enumerable: false,
       configurable: false,
@@ -157,15 +165,15 @@ const Component = (name = required('name'), config = required('config')) => {
 
     this.lifecycle.state = 'init'
 
-    Object.defineProperty(this, '___children', {
+    Object.defineProperty(this, symbols.children, {
       value: code.render.apply(stage, [parentEl, this, code.context]),
       writable: false,
       enumerable: false,
       configurable: false,
     })
 
-    Object.defineProperty(this, '___slots', {
-      value: this.___children.filter((child) => child.___isSlot),
+    Object.defineProperty(this, symbols.slots, {
+      value: this[symbols.children].filter((child) => child[symbols.isSlot]),
       writable: false,
       enumerable: false,
       configurable: false,
@@ -173,16 +181,16 @@ const Component = (name = required('name'), config = required('config')) => {
 
     code.effects.forEach((eff) => {
       effect(() => {
-        eff.apply(stage, [this, this.___children, code.context])
+        eff.apply(stage, [this, this[symbols.children], code.context])
       })
     })
 
-    if (this.___watchers) {
-      Object.keys(this.___watchers).forEach((watchKey) => {
+    if (this[symbols.watchers]) {
+      Object.keys(this[symbols.watchers]).forEach((watchKey) => {
         let old = this[watchKey]
-        effect(() => {
-          if (old !== this[watchKey]) {
-            this.___watchers[watchKey].apply(this, [this[watchKey], old])
+        effect((force = false) => {
+          if (old !== this[watchKey] || force === true) {
+            this[symbols.watchers][watchKey].apply(this, [this[watchKey], old])
             old = this[watchKey]
           }
         })

package/src/components/RouterView.js

@@ -16,14 +16,14 @@
  */
 
 import Component from '../component.js'
-import Router from '../router.js'
+import Router from '../router/router.js'
 
 let handler
 
 export default () =>
   Component('RouterView', {
     template: `
-      <Element></Element>
+      <Element w="100%" height="100%"></Element>
     `,
     hooks: {
       ready() {

package/src/components/Sprite.js

@@ -17,6 +17,8 @@
 
 import Component from '../component.js'
 
+import symbols from '../lib/symbols.js'
+
 export default () =>
   Component('Sprite', {
     template: `
@@ -36,7 +38,7 @@ export default () =>
             : this.map[this.frame]
 
         if (this.spriteTexture && options) {
-          return this.___renderer.createTexture('SubTexture', {
+          return this[symbols.renderer].createTexture('SubTexture', {
             texture: this.spriteTexture,
             x: options.x,
             y: options.y,
@@ -48,7 +50,7 @@ export default () =>
     },
     hooks: {
       ready() {
-        this.spriteTexture = this.___renderer.createTexture('ImageTexture', {
+        this.spriteTexture = this[symbols.renderer].createTexture('ImageTexture', {
           src: `${window.location.protocol}//${window.location.host}/${this.image}`,
         })
       },

package/src/element.js

@@ -19,6 +19,7 @@ import { renderer } from './launch.js'
 import colors from './lib/colors/colors.js'
 
 import { Log } from './lib/log.js'
+import symbols from './lib/symbols.js'
 
 const isTransition = (value) => {
   return typeof value === 'object' && 'transition' in value
@@ -174,8 +175,8 @@ const Element = {
     }
     this.initData = data
 
-    if (props.___isSlot) {
-      this.___isSlot = true
+    if (props[symbols.isSlot]) {
+      this[symbols.isSlot] = true
     }
 
     transformations.remap(props)
@@ -192,15 +193,13 @@ const Element = {
     this.node = props.__textnode ? renderer.createTextNode(props) : renderer.createNode(props)
 
     if (props['@loaded']) {
-      const event = props.__textnode ? 'textLoaded' : 'txLoaded'
-      this.node.on(event, (el, { width: w, height: h }) => {
-        props['@loaded']({ w, h }, this)
+      this.node.on('loaded', (el, { type, dimensions }) => {
+        props['@loaded']({ w: dimensions.width, h: dimensions.height, type }, this)
       })
     }
 
     if (props['@error']) {
-      const event = props.__textnode ? 'textFailed' : 'txFailed'
-      this.node.on(event, (el, error) => {
+      this.node.on('failed', (el, error) => {
         props['@error'](error, this)
       })
     }
@@ -253,7 +252,7 @@ const Element = {
     // works for now
     prop = Object.keys(props).pop()
 
-    if (typeof value === 'string' && props[prop].endsWith('%')) {
+    if (typeof props[prop] === 'string' && props[prop].endsWith('%')) {
       transformations.percentage.call(this, props, prop)
     }
 
@@ -263,8 +262,11 @@ const Element = {
         easing:
           typeof value === 'object' ? ('function' in value ? value.function : 'ease') : 'ease',
       })
-
-      value.delay ? setTimeout(() => f.start(), value.delay) : f.start()
+      return new Promise((resolve) => {
+        value.delay
+          ? setTimeout(() => f.start().waitUntilStopped().then(resolve), value.delay)
+          : f.start().waitUntilStopped().then(resolve)
+      })
     }
   },
 }

package/src/focus.js

@@ -15,6 +15,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import symbols from './lib/symbols.js'
+import { navigating } from './router/router.js'
+
 let focusedComponent = null
 
 export default {
@@ -34,6 +37,7 @@ export default {
     }
   },
   input(key, event) {
+    if (navigating === true) return
     const focusChain = walkChain([focusedComponent], key)
     const componentWithInputEvent = focusChain.shift()
 
@@ -42,10 +46,10 @@ export default {
         focusChain.reverse().forEach((component) => component.unfocus())
         componentWithInputEvent.focus()
       }
-      if (componentWithInputEvent.___inputEvents[key]) {
-        componentWithInputEvent.___inputEvents[key].call(componentWithInputEvent, event)
-      } else if (componentWithInputEvent.___inputEvents.any) {
-        componentWithInputEvent.___inputEvents.any.call(componentWithInputEvent, event)
+      if (componentWithInputEvent[symbols.inputEvents][key]) {
+        componentWithInputEvent[symbols.inputEvents][key].call(componentWithInputEvent, event)
+      } else if (componentWithInputEvent[symbols.inputEvents].any) {
+        componentWithInputEvent[symbols.inputEvents].any.call(componentWithInputEvent, event)
       }
     }
   },
@@ -53,9 +57,9 @@ export default {
 
 const walkChain = (components, key) => {
   if (
-    components[0].___inputEvents &&
-    (typeof components[0].___inputEvents[key] === 'function' ||
-      typeof components[0].___inputEvents.any === 'function')
+    components[0][symbols.inputEvents] &&
+    (typeof components[0][symbols.inputEvents][key] === 'function' ||
+      typeof components[0][symbols.inputEvents].any === 'function')
   ) {
     return components
   } else if (components[0].parent) {

package/src/lib/codegenerator/generator.js

@@ -56,7 +56,7 @@ const generateElementCode = function (
 
   renderCode.push(`
     if(!${elm}) {
-      ${elm} = this.element({componentId: component.___id, parent: parent || 'root'})
+      ${elm} = this.element({componentId: component[Symbol.for('id')], parent: parent || 'root'})
     }
     const elementConfig${counter} = {}
   `)
@@ -67,14 +67,14 @@ const generateElementCode = function (
   Object.keys(templateObject).forEach((key) => {
     if (key === 'type') {
       if (templateObject[key] === 'Slot') {
-        renderCode.push(`elementConfig${counter}['___isSlot'] = true`)
+        renderCode.push(`elementConfig${counter}[Symbol.for('isSlot')] = true`)
       }
       return
     }
 
     if (key === 'slot') {
       renderCode.push(`
-        elementConfig${counter}['parent'] = component.___slots.filter(slot => slot.ref === '${templateObject.slot}').shift() || component.___slots[0] || parent
+        elementConfig${counter}['parent'] = component[Symbol.for('slots')].filter(slot => slot.ref === '${templateObject.slot}').shift() || component[Symbol.for('slots')][0] || parent
       `)
     }
 
@@ -120,7 +120,7 @@ const generateComponentCode = function (
   renderCode.push(`
     const cmp${counter} =
       (context.components && context.components['${templateObject.type}']) ||
-      component.___components['${templateObject.type}']
+      component[Symbol.for('components')]['${templateObject.type}']
   `)
 
   if ('key' in templateObject) {
@@ -152,7 +152,7 @@ const generateComponentCode = function (
     if (key === 'type') return
     if (isReactiveKey(key)) {
       this.effectsCode.push(`
-        ${elm}.___props['${key.substring(1)}'] = ${interpolate(
+        ${elm}[Symbol.for('props')]['${key.substring(1)}'] = ${interpolate(
         templateObject[key],
         options.component
       )}`)
@@ -171,12 +171,12 @@ const generateComponentCode = function (
 
   renderCode.push(`
     if(!${elm}) {
-      ${elm} = (context.components && context.components['${templateObject.type}'] || component.___components['${templateObject.type}'] || (() => { console.log('component ${templateObject.type} not found')})).call(null, {props: props${counter}}, ${parent}, component)
-      if (${elm}.___slots[0]) {
-        parent = ${elm}.___slots[0]
+      ${elm} = (context.components && context.components['${templateObject.type}'] || component[Symbol.for('components')]['${templateObject.type}'] || (() => { console.log('component ${templateObject.type} not found')})).call(null, {props: props${counter}}, ${parent}, component)
+      if (${elm}[Symbol.for('slots')][0]) {
+        parent = ${elm}[Symbol.for('slots')][0]
         component = ${elm}
       } else {
-        parent = ${elm}.___children[0]
+        parent = ${elm}[Symbol.for('children')][0]
       }
     }
   `)