@lightningjs/blits 0.3.14 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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_
+
+- Added support for slots
+- Added support for defining custom keymapping
+- Improved error handling of the template parser
+
 ## v0.3.14
 
 _19 oct 2023_

package/boilerplate/package.json

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

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.3.14",
+  "version": "0.4.0",
   "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

@@ -16,12 +16,13 @@
  */
 
 import Component from './component.js'
-
 import Focus from './focus.js'
+import Settings from './settings.js'
+
+import symbols from './lib/symbols.js'
 
 const Application = (config) => {
-  // make configurable?
-  const mapping = {
+  const defaultKeyMap = {
     ArrowLeft: 'left',
     ArrowRight: 'right',
     ArrowUp: 'up',
@@ -30,22 +31,36 @@ const Application = (config) => {
     ' ': 'space',
     Backspace: 'back',
     Escape: 'escape',
+    37: 'left',
+    39: 'right',
+    38: 'up',
+    40: 'down',
+    13: 'enter',
+    32: 'space',
+    8: 'back',
+    27: 'escape',
   }
 
-  const handler = (e) => {
-    const key = mapping[e.key] || e.key
-    Focus.input(key, e)
-  }
+  config.hooks = config.hooks || {}
 
-  document.addEventListener('keydown', handler)
+  let handler
 
-  config.hooks = config.hooks || {}
-  config.hooks.___init = function () {
-    Focus.set(this)
+  config.hooks[symbols.destroy] = function () {
+    document.removeEventListener('keydown', handler)
   }
 
-  config.hooks.___destroy = function () {
-    document.removeEventListener('keydown', handler)
+  config.hooks[symbols.init] = function () {
+    const keyMap = { ...defaultKeyMap, ...Settings.get('keymap', {}) }
+
+    handler = (e) => {
+      const key = keyMap[e.key] || keyMap[e.keyCode] || e.key || e.keyCode
+      Focus.input(key, e)
+    }
+
+    document.addEventListener('keydown', handler)
+
+    // 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,21 +120,28 @@ const Component = (name = required('name'), config = required('config')) => {
     }
 
     this.parent = parentComponent
+    this.wrapper = parentEl
 
     Object.defineProperties(this, {
+      type: {
+        value: name,
+        writable: false,
+        enumerable: true,
+        configurable: false,
+      },
       componentId: {
         value: createHumanReadableId(name),
         writable: false,
         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,
@@ -140,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,
@@ -151,25 +165,32 @@ 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, symbols.slots, {
+      value: this[symbols.children].filter((child) => child[symbols.isSlot]),
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    })
+
     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,6 +175,10 @@ const Element = {
     }
     this.initData = data
 
+    if (props[symbols.isSlot]) {
+      this[symbols.isSlot] = true
+    }
+
     transformations.remap(props)
     Object.keys(props).forEach((prop) => {
       if (transformations[prop]) {
@@ -188,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)
       })
     }
@@ -249,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)
     }
 
@@ -259,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/launch.d.ts

@@ -86,7 +86,11 @@ export interface Settings {
   /**
    * Fonts to be used in the Application
    */
-  fonts?: Font[]
+  fonts?: Font[],
+  /**
+   * Custom keymapping
+   */
+  keymap?: object
 }
 
 /**

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} = {}
   `)
@@ -65,7 +65,18 @@ const generateElementCode = function (
   delete templateObject['children']
 
   Object.keys(templateObject).forEach((key) => {
-    if (key === 'type') return
+    if (key === 'type') {
+      if (templateObject[key] === 'Slot') {
+        renderCode.push(`elementConfig${counter}[Symbol.for('isSlot')] = true`)
+      }
+      return
+    }
+
+    if (key === 'slot') {
+      renderCode.push(`
+        elementConfig${counter}['parent'] = component[Symbol.for('slots')].filter(slot => slot.ref === '${templateObject.slot}').shift() || component[Symbol.for('slots')][0] || parent
+      `)
+    }
 
     if (isReactiveKey(key)) {
       this.effectsCode.push(
@@ -109,13 +120,15 @@ 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) {
     options.key = interpolate(templateObject.key, options.component)
   }
 
+  const children = templateObject.children
+  delete templateObject.children
   generateElementCode.call(this, templateObject, parent, { ...options, ...{ holder: true } })
 
   parent = options.key ? `elms[${counter}][${options.key}]` : `elms[${counter}]`
@@ -139,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
       )}`)
@@ -158,9 +171,18 @@ 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)
+      ${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}[Symbol.for('children')][0]
+      }
     }
   `)
+
+  counter++
+  generateElementCode.call(this, { children }, false, { ...options })
 }
 
 const generateForLoopCode = function (templateObject, parent) {
@@ -210,14 +232,14 @@ const generateForLoopCode = function (templateObject, parent) {
     `)
   }
 
-  if (templateObject.type !== 'Element') {
-    generateComponentCode.call(ctx, templateObject, false, {
+  if (templateObject.type === 'Element' || templateObject.type === 'Slot') {
+    generateElementCode.call(ctx, templateObject, parent, {
       key: 'scope.key',
       component: 'scope.',
       forceEffect: false,
     })
   } else {
-    generateElementCode.call(ctx, templateObject, parent, {
+    generateComponentCode.call(ctx, templateObject, false, {
       key: 'scope.key',
       component: 'scope.',
       forceEffect: false,
@@ -248,10 +270,10 @@ const generateCode = function (templateObject, parent = false) {
       if (Object.keys(childTemplateObject).indexOf(':for') > -1) {
         generateForLoopCode.call(this, childTemplateObject, parent)
       } else {
-        if (childTemplateObject.type !== 'Element') {
-          generateComponentCode.call(this, childTemplateObject, parent)
-        } else {
+        if (childTemplateObject.type === 'Element' || childTemplateObject.type === 'Slot') {
           generateElementCode.call(this, childTemplateObject, parent)
+        } else {
+          generateComponentCode.call(this, childTemplateObject, parent)
         }
       }
     })