@lightningjs/blits 1.9.2 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.10.1
+
+_15 nov 2024_
+
+- Upgraded to renderer 2.7.1
+- Added documentation on Router
+
+## v1.10.0
+
+_8 nov 2024_
+
+- Fixed issue with back button not bubbling to App component after last page in router history is popped
+- Added `align-items` attribute to Layout component
+- Fixed issue with watching nested state variables and global state
+- Upgraded to renderer 2.6.2
+- Fixed issue with white background for Elements with falsy src attribute
+- Fixed issue with calling focus on component that already is focussed
+
+
 ## v1.9.2
 
 _5 nov 2024_

package/docs/_sidebar.md

@@ -24,6 +24,9 @@
   - [Directives](/built-in/directives.md)
   - [For loop](/built-in/for-loop.md)
   - [Layout](/built-in/layout.md)
+- Router
+  - [Basics](/router/basics.md)
+  - [Hooks](/router/hooks.md)
 - Plugins
   - [Text-to-Speech / Announcer](/plugins/text-to-speech-announcer.md)
   - [Language](/plugins/language.md)

package/docs/built-in/layout.md

@@ -37,6 +37,14 @@ In order to align vertically use `<Layout direction="vertical"></Layout>`. And u
 
 By default the Layout-component places each Element directly besides (or below) the previous one. By adding the `gap`-attribute you can control how much space will be added between each Element or Component. The `gap`-attribute accepts a number in pixels.
 
+### Aligning items
+
+The layout component positions its children based on the provided direction (`horizontal` or `vertical`). With the `align-items`-attribute you can specify how to align the children on the opposite axis:
+
+- `start` (the default value) - aligns the children in the _top_ for horizontal layouts, and on the _left_ for vertical layouts
+- `center` - align the children in the center
+- `end` - aligns the children in the _bottom_ for horizontal layouts, and on the _right_ for vertical layouts
+
 ### Dynamic dimensions
 
 For the Layout component to work properly, the direct children all need to have dimensions (i.e `w` and `h` attributes). The exception here being Text elements.

package/docs/router/basics.md

@@ -0,0 +1,98 @@
+# Router Basics
+
+The Blits framework comes with a built-in, performant router that eliminates the need to pull in any additional dependencies into your App.
+
+Before we dive into the details, let's first touch base on some key concepts.
+
+## Key concepts
+
+### Pages are regular Blits Components
+
+The router in Blits is primarily used to navigate between Pages in your App. In the context of a Blits App, a Page is just a regular Blits Component. Usually it will be a Component that fills the entire screen. But it is also possible to have only a smaller portion of the screen contain dynamic routed content.
+
+### URL hash
+
+When navigating to a page, the hash in the URL of the browser will automatically be updated (i.e. `http://localhost:8080/#my/page`) to match the current page. The hash can also be used to _deep-link_ directly into your application. Upon first load, the router functionality will evaluate the URL hash and try to match that to a defined route. If a matching route is found, it will load that page as deep linked content.
+
+## Defining Routes
+
+Routes are defined in the main Application component, as an Array under the `routes` key of the configuration object.
+
+Each route in this array, is an Object literal that includes the following key properties:
+
+- `path` - the url hash to the route (i.e. `/my/page`)
+- `component` - the Blits component to render for the route. This can be a direct reference, but also a promise or a dynamic import that resolves to a Blits component
+- `hooks` (optional) - hooks such as `before` can be defined to execute code before navigating to the route
+- `options` (optional) - additional options defining route behaviour, such as `keepAlive` and `inHistory`
+- `transitions` (optional) - used to define custom transitions between pages
+
+### Dynamic routes with params
+
+Besides static routes such as `/account` and `/settings/wifi/advanced`, the Blits router also supports dynamic routes where URI parts can contain params.
+
+To define a param in a route path prefix a string with a colon (`:`), followed by the name of the param, e.g. `/movies/:genre/:id`. This route path will match a URI hash such as `#/movies/sci-fi/65281918`. The router will take the params and inject them as a `prop` into the Page that's being navigated to.
+
+To access these props in the Page component, they must first be defined in the Component first (i.e. `props: ['genre', 'id']`). Once defined, the values (`sci-fi` and `65281918`) in this case, will be available on the `this` scope, as with any regular Component.
+
+
+## Router view
+
+The routes are loaded into a `<RouterView />` component, which acts as a placeholder for the routed Page components.
+
+The `<RouterView />` component can be positioned and sized as you would expect from a normal Blits Component.
+
+
+```js
+export default Blits.Application({
+  template: `
+    <Element>
+      <RouterView x="300" y="200" w="1520" h="680" />
+    </Element>
+  `,
+  routes: [
+      { path: '/', component: Home },
+      { path: '/details', component: () => import('./pages/Details.js'), },
+      { path: '/account',
+        component: () => {
+          // imagine this is an API call or some other async action
+          return new Promise((resolve) => {
+            resolve(Account)
+          })
+        }
+      }
+  ],
+  // ...
+})
+```
+
+## Navigation
+
+Each component in a routed Blits app has a `this.$router` object that provides access to the Router instance. It can be used to programmatically navigate to pages, by calling the `to()` method on it.
+
+The `this.$router.to()`-methods accepts 3 arguments:
+
+- `path` - the path of the route to navigate to
+- `data` (optional) - an object with data to pass into the page as `props`
+- `options` (optional) - additional options defining route behaviour, such as `keepAlive` and `inHistory` (these will overwrite any options specified for a route in the routes array)
+
+```js
+export default Blits.Component('Poster', {
+  input: {
+    enter() {
+      this.$router.to('/movie/details', {id: '1', img: 'details.png'}, {inHistory: false})
+    }
+  }
+})
+```
+
+Whenever you navigate to a new page, the URL hash will automatically be updated. Unless specified otherwise, navigating to a new page, will add that route to the history stack. The `back` input action is automatically wired up to navigate back down the history stack.
+
+## Router API
+
+The Router API provides several useful methods and properties for managing routes and navigation:
+
+- `this.$router.to()` - navigating to a different location (as discussed above)
+- `this.$router.back()` - programmatically navigate back down the history stack
+- `this.$router.currentRoute` - retrieve the current route
+- `this.$router.routes` - retrieve the list of all routes
+- `this.$router.navigating` - retrieve the current navigating state

package/docs/router/hooks.md

@@ -0,0 +1,70 @@
+# Router Hooks
+
+The Blits router supports hooks that allow you to execute code at specific points during the navigation process.
+
+Hooks are defined per route in the optional `hooks` key within the Route configuration object.
+
+> Currently, the Blits router only supports the before hook, with additional hooks planned for future releases.
+
+## Before hook
+
+The before hook is executed before the navigation occurs. It can be used for checks, such as verifying user authentication for a specific route, for pre-fetching data, or for executing logic like sending stats beacons.
+
+The before hook is defined as a function that receives 2 arguments: the Route object that is being navigated `to`. And the Route object that is being navigated away `from`.
+
+```js
+export default Blits.Application({
+  // ...
+  routes: [
+      {
+        path: '/',
+        component: Home,
+        hooks: {
+          before(to, from) {
+            // custom logic
+          }
+        }
+      }
+  ],
+  // ...
+})
+```
+
+The before hook can optionally return a value, which will influence the behaviour of the route change:
+
+- when  `false` is returned, the router will fail to finish the routing, and act as if _no matching route was found_
+- when a `string` is returned, the router will interpret this a _new route path to redirect to_
+- when an `object` is returned, the router will interpret this as a route object, allowing to _modify (or completely replace) the route object_ being navigated to
+
+Returning an `object` is a simple, yet powerful, mechanism to add advanced runtime configuration to your routes. A common scenario is to overwrite certain parts of the route object provided in the `to`-argument, such as the route options (such as `inHistory` or `stayAlive`) or define conditional page transitions.
+
+It's also possible to add custom data to the route object in the `key` object. Custom data should be an object literal. When the new page loads, the keys in the `data` object are injected into the Component as `props`.
+
+```js
+export default Blits.Application({
+  // ...
+  routes: [
+      {
+        path: '/video/details/:id',
+        component: Details,
+        hooks: {
+          before(to, from) {
+            // redirect to an error page when id is not a number
+            if(isNaN(to.params.id)) {
+              return '/not-valid'
+            }
+            // set a different transition when navigating from home page
+            if(from && from.path === '/home') {
+              to.transition = slideInTransition
+            }
+            // add custom data
+            to.data.title = 'Hello World'
+            // finally return the modified route object
+            return to
+          }
+        }
+      }
+  ],
+  // ...
+})
+```

package/docs/router/transitions.md

@@ -0,0 +1,146 @@
+# Router Transitions
+
+Page transitions add a layer of visual polish to your application by animating the change between routes.
+
+When the router in Blits navigates to a new page, it automatically applies a subtle _fade-in / fade-out_ transition. Blits also allows to specify custom transitions on a per-route basis.
+
+## Defining Route Transitions
+
+In the Route object, the `transition` key can be used to specify which transition should be applied when navigating _to_ that route.
+
+It accepts a _Transition_ object, with 3 optional keys: `before`, `in`, `out`.
+
+### Before
+
+The `before` key is used to set a property to a certain value _before_ the page transition starts. The properties are set on the page that is being navigated _to_. For example, it can be used to position the page out of screen by setting the `x` value to a negative value, in order to create a _slide in from the right_ effect. Or the `alpha` property can be set to `0` if you want to create a _fade-in_ effect.
+
+```js
+const pageTransition = {
+  // position the new page outside the screen on the left side
+  before: {
+    prop: 'x',
+    value: -1920
+  }
+}
+```
+
+In order to set multiple properties to an initial state, an Array of objects can be assigned to the `before` key.
+
+```js
+const pageTransition = {
+  // position the new page outside the screen on the left side
+  // and set the alpha to 0
+  before: [{
+    prop: 'x',
+    value: -1920
+  },{
+    prop: 'alpha',
+    value: 0
+  }]
+}
+```
+
+### In
+
+The `in`-key is used to define how the new page should transition _into_ the screen, given the initial defaults, in combination with any properties set in the optional `before` key.
+
+The transition is defined by a _Transition_ object, consisting of:
+
+- `prop` - the property to apply the transition on
+- `value` - the value to transition to
+- `duration` (optional) - the duration of the transition in milliseconds (defaults to `300ms`)
+- `easing` (optional) - the easing function applied to the transition (defaults to `ease-in`)
+
+```js
+const pageTransition = {
+  // position the new page outside the screen on the left side
+  before: {
+    prop: 'x',
+    value: -1920
+  },
+  // transition the new page from outside, into the screen
+  in: {
+    prop: 'x',
+    value: 0,
+    duration: 800,
+    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
+  }
+}
+```
+
+In order to transition multiple properties, an Array of objects can be assigned to the `in` key.
+
+```js
+const pageTransition = {
+  // position the new page outside the screen on the left side
+  // and set the alpha to 0
+  before: [{
+    prop: 'x',
+    value: -1920
+  },{
+    prop: 'alpha',
+    value: 0
+  }],
+  // transition the new page from outside, into the screen
+  // and transition the alpha from 0 to 1
+  in: [{
+    prop: 'x',
+    value: 0,
+    duration: 800,
+    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
+  },{
+    prop: 'alpha',
+    value: 1,
+    duration: 500,
+  }]
+}
+```
+
+### Out
+
+Finally the `out`-key is used to define how the old page should transition _out of_ the screen.
+
+Similar to the `in`-transition, the `out`-transition is defined by a _Transition object_, consisting of:
+
+- `prop` - the property to apply the transition on
+- `value` - the value to transition to
+- `duration` (optional) - the duration of the transition in milliseconds (defaults to `300ms`)
+- `easing` (optional) - the easing function applied to the transition (defaults to `ease-in`)
+
+And in order to transition multiple properties at the same time during the _out_ transition, an Array of transition objects can be supplied.
+
+
+```js
+const pageTransition = {
+  // position the new page outside the screen on the left side
+  // and set the alpha to 0
+  before: [{
+    prop: 'x',
+    value: -1920
+  },{
+    prop: 'alpha',
+    value: 0
+  }],
+  // transition the new page from outside, into the screen
+  // and transition the alpha from 0 to 1
+  in: [{
+    prop: 'x',
+    value: 0,
+    duration: 800,
+    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
+  },{
+    prop: 'alpha',
+    value: 1,
+    duration: 500,
+  }],
+  // slide up the old page
+  // while rotating
+  out: [{
+    prop: 'y',
+    value: -1080
+  },{
+    prop: 'rotate',
+    value: 720
+  }]
+}
+```

package/docs/sidebar.json

@@ -108,6 +108,19 @@
       }
     ]
   },
+  {
+    "text": "Router",
+    "items": [
+      {
+        "text": "Basics",
+        "link": "/router/basics"
+      },
+      {
+        "text": "Hooks",
+        "link": "/router/hooks"
+      }
+    ]
+  },
   {
     "text": "Plugins",
     "items": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.9.2",
+  "version": "1.10.1",
   "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.6.0"
+    "@lightningjs/renderer": "^2.7.1"
   },
   "repository": {
     "type": "git",

package/src/component.js

@@ -176,6 +176,7 @@ const Component = (name = required('name'), config = required('config')) => {
       for (let i = 0; i < watcherkeysLength; i++) {
         let target = this
         let key = watcherkeys[i]
+        const watchKey = key
         // when dot notation used, find the nested target
         if (key.indexOf('.') > -1) {
           const keys = key.split('.')
@@ -190,7 +191,7 @@ const Component = (name = required('name'), config = required('config')) => {
         effect((force = false) => {
           const newValue = target[key]
           if (old !== newValue || force === true) {
-            this[symbols.watchers][key].apply(this, [newValue, old])
+            this[symbols.watchers][watchKey].apply(this, [newValue, old])
             old = newValue
           }
         })

package/src/components/RouterView.js

@@ -60,8 +60,11 @@ export default () =>
       },
     },
     input: {
-      back() {
-        Router.back()
+      back(e) {
+        const navigating = Router.back()
+        if (navigating === false) {
+          this.parent.$focus(e)
+        }
       },
     },
   })

package/src/components/RouterView.orig.js

@@ -44,8 +44,11 @@ export default () =>
       },
     },
     input: {
-      back() {
-        Router.back()
+      back(e) {
+        const navigating = Router.back()
+        if (navigating === false) {
+          this.parent.$focus(e)
+        }
       },
     },
   })

package/src/engines/L3/element.js

@@ -24,9 +24,11 @@ import Settings from '../../settings.js'
 
 const layoutFn = function (config) {
   let offset = 0
-  const xy = config.direction === 'vertical' ? 'y' : 'x'
-  const wh = config.direction === 'vertical' ? 'height' : 'width'
-  const opositeWh = config.direction === 'vertical' ? 'width' : 'height'
+  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 children = this.children
   const childrenLength = children.length
@@ -34,11 +36,11 @@ const layoutFn = function (config) {
   const gap = config.gap || 0
   for (let i = 0; i < childrenLength; i++) {
     const node = children[i]
-    node[xy] = offset
+    node[position] = offset
     // todo: temporary text check, due to 1px width of empty text node
-    if (wh === 'width') {
+    if (dimension === 'width') {
       offset += node.width + (node.width !== ('text' in node ? 1 : 0) ? gap : 0)
-    } else if (wh === 'height') {
+    } else if (dimension === 'height') {
       offset +=
         'text' in node
           ? node.width > 1
@@ -48,11 +50,25 @@ const layoutFn = function (config) {
           ? node.height + gap
           : 0
     }
-    otherDimension = Math.max(otherDimension, node[opositeWh])
+    otherDimension = Math.max(otherDimension, node[oppositeDimension])
   }
   // adjust the size of the layout container
-  this[wh] = offset - gap
-  this[opositeWh] = otherDimension
+  this[dimension] = offset - gap
+  this[oppositeDimension] = otherDimension
+
+  const align = {
+    start: 0,
+    end: 1,
+    center: 0.5,
+  }[config['align-items'] || 'start']
+
+  if (align !== 0) {
+    for (let i = 0; i < childrenLength; i++) {
+      const node = children[i]
+      node[oppositePosition] = otherDimension
+      node[oppositeMount] = align
+    }
+  }
 }
 
 const isTransition = (value) => {
@@ -146,7 +162,7 @@ const propsTransformer = {
   set src(v) {
     this.props['src'] = v
     if (this.raw['color'] === undefined) {
-      this.props['color'] = 0xffffffff
+      this.props['color'] = this.props['src'] ? 0xffffffff : 0x00000000
     }
   },
   set texture(v) {
@@ -225,7 +241,15 @@ const propsTransformer = {
     }
   },
   set show(v) {
-    this.props['alpha'] = v ? 1 : 0
+    if (v) {
+      this.props['alpha'] = 1
+      this.props['width'] = this.raw['w'] || this.raw['width']
+      this.props['height'] = this.raw['h'] || this.raw['height']
+    } else {
+      this.props['alpha'] = 0
+      this.props['width'] = 0
+      this.props['height'] = 0
+    }
   },
   set alpha(v) {
     this.props['alpha'] = v

package/src/focus.js

@@ -38,6 +38,7 @@ export default {
     return focusedComponent
   },
   set(component, event) {
+    if (component === focusedComponent) return
     clearTimeout(setFocusTimeout)
     focusedComponent && focusedComponent !== component.parent && focusedComponent.unfocus()
     focusChain.reverse().forEach((cmp) => cmp.unfocus())

package/src/lib/codegenerator/generator.js

@@ -442,10 +442,18 @@ const generateForLoopCode = function (templateObject, parent) {
 
   // inject the destroy code in the correct spot
   ctx.renderCode.splice(indexToInjectDestroyCode, 0, ...destroyCode)
+
+  let effectKey = `${interpolate(result[2], '')}`
+
+  // Get the last property from nested path
+  if (effectKey && effectKey.includes('.')) {
+    effectKey = effectKey.match(/[^.]+$/)[0]
+  }
+
   ctx.renderCode.push(`
     effect(() => {
       forloop${forStartCounter}(${cast(result[2], ':for')}, elms, created${forStartCounter})
-    }, '${interpolate(result[2], '')}')
+    }, '${effectKey}' )
   `)
 
   outerScopeEffects.forEach((effect) => {

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

@@ -2055,6 +2055,182 @@ test('Generate code for a template with a simple for-loop on an Element', (asser
   assert.end()
 })
 
+test('Generate code for a template with a simple for-loop on an Element, Using data from appState plugin', (assert) => {
+  const templateObject = {
+    children: [
+      {
+        [Symbol.for('componentType')]: 'Element',
+        children: [
+          {
+            [Symbol.for('componentType')]: 'Element',
+            ':for': 'item in $$appState.list',
+          },
+        ],
+      },
+    ],
+  }
+
+  const expectedRender = `
+  function anonymous(parent, component, context, components, effect, getRaw) {
+    const elms = []
+    let componentType
+    const rootComponent = component
+    let propData
+    const elementConfig0 = {}
+    elms[0] = this.element({ parent: parent || 'root' }, component)
+    elms[0].populate(elementConfig0)
+    parent = elms[0]
+    const created1 = []
+    const forloop1 = (collection = [], elms, created) => {
+        const rawCollection = getRaw(collection)
+        const keys = new Set()
+        let l = rawCollection.length
+        while (l--) {
+            const item = rawCollection[l]
+            const index = l
+            keys.add('' + l)
+        }
+        let i = created.length
+        while (i--) {
+            if (keys.has(created[i]) === false) {
+                const key = created[i]
+                elms[1][key] && elms[1][key].destroy()
+                delete elms[1][key]
+            }
+        }
+        created.length = 0
+        const length = rawCollection.length
+        for (let __index = 0; __index < length; __index++) {
+            const scope = Object.create(component)
+            parent = elms[0]
+            scope['index'] = __index
+            scope['item'] = rawCollection[__index]
+            scope['key'] = '' + __index
+            created.push(scope.key)
+            parent = elms[0]
+            if (elms[1] === undefined) {
+                elms[1] = {}
+            }
+            const elementConfig1 = {}
+            if (elms[1][scope.key] === undefined) {
+                elms[1][scope.key] = this.element({ parent: parent || 'root' }, component)
+            }
+            if (elms[1][scope.key].nodeId === undefined) {
+                elms[1][scope.key].populate(elementConfig1)
+            }
+        }
+    }
+    effect(() => {
+        forloop1(component.$appState.list, elms, created1)
+    }, 'list')
+    return elms
+  }
+  `
+
+  const actual = generator.call(scope, templateObject)
+
+  assert.equal(
+    normalize(actual.render.toString()),
+    normalize(expectedRender),
+    'Generator should return a render function with the correct code using data from appState plugin'
+  )
+
+  assert.ok(
+    Array.isArray(actual.effects) && actual.effects.length === 0,
+    'Generator should return an empty effect array'
+  )
+
+  assert.end()
+})
+
+test('Generate code for a template with a simple for-loop on an Element, Using data from nested state property', (assert) => {
+  const templateObject = {
+    children: [
+      {
+        [Symbol.for('componentType')]: 'Element',
+        children: [
+          {
+            [Symbol.for('componentType')]: 'Element',
+            ':for': 'item in $content.data',
+          },
+        ],
+      },
+    ],
+  }
+
+  const expectedRender = `
+  function anonymous(parent, component, context, components, effect, getRaw) {
+    const elms = []
+    let componentType
+    const rootComponent = component
+    let propData
+    const elementConfig0 = {}
+    elms[0] = this.element({ parent: parent || 'root' }, component)
+    elms[0].populate(elementConfig0)
+    parent = elms[0]
+    const created1 = []
+    const forloop1 = (collection = [], elms, created) => {
+        const rawCollection = getRaw(collection)
+        const keys = new Set()
+        let l = rawCollection.length
+        while (l--) {
+            const item = rawCollection[l]
+            const index = l
+            keys.add('' + l)
+        }
+        let i = created.length
+        while (i--) {
+            if (keys.has(created[i]) === false) {
+                const key = created[i]
+                elms[1][key] && elms[1][key].destroy()
+                delete elms[1][key]
+            }
+        }
+        created.length = 0
+        const length = rawCollection.length
+        for (let __index = 0; __index < length; __index++) {
+            const scope = Object.create(component)
+            parent = elms[0]
+            scope['index'] = __index
+            scope['item'] = rawCollection[__index]
+            scope['key'] = '' + __index
+            created.push(scope.key)
+            parent = elms[0]
+            if (elms[1] === undefined) {
+                elms[1] = {}
+            }
+            const elementConfig1 = {}
+            if (elms[1][scope.key] === undefined) {
+                elms[1][scope.key] = this.element({ parent: parent || 'root' }, component)
+            }
+            if (elms[1][scope.key].nodeId === undefined) {
+                elms[1][scope.key].populate(elementConfig1)
+            }
+        }
+    }
+    effect(() => {
+        forloop1(component.content.data, elms, created1)
+    }, 'data')
+    return elms
+  }
+  `
+
+  const actual = generator.call(scope, templateObject)
+
+  assert.equal(
+    normalize(actual.render.toString()),
+    normalize(expectedRender),
+    'Generator should return a render function with the correct code using data from nested state property'
+  )
+
+  assert.ok(
+    Array.isArray(actual.effects) && actual.effects.length === 0,
+    'Generator should return an empty effect array'
+  )
+
+  assert.end()
+})
+
 test('Generate code for a template with a simple for-loop on an Element with a custom index key', (assert) => {
   const templateObject = {
     children: [