@lightningjs/blits 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v1.10.1
+
+_15 nov 2024_
+
+- Upgraded to renderer 2.7.1
+- Added documentation on Router
+
 ## v1.10.0
 
 _8 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/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.10.0",
+  "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.2"
+    "@lightningjs/renderer": "^2.7.1"
   },
   "repository": {
     "type": "git",

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: [