Merge pull request #271 from lightning-js/dev

Release 1.18.0

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v1.18.0
+
+_27 jan 2025_
+
+- Added backtracking functionality to the Router
+- Upgraded to latest version of the renderer (2.10.0)
+- Changed setting `textureProcessingLimit` to `textureProcessingTimeLimit`
+
+
 ## v1.17.1
 
 _24 jan 2025_

docs/router/basics.md

@@ -96,6 +96,42 @@ export default Blits.Component('Poster', {
 
 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.
 
+## Deeplinking
+
+The Router plugin has support for deeplinking. When the App is loaded with a URL hash (i.e. `#/pages/settings/network`), the router will try to match that hash to a defined route. This means that your app can be deep linked into, by simply providing the correct URL hash.
+
+This is an important feature for several reasons:
+
+- It will allow external sources (like operators and UIs) to link directly to a specific page in your app (i.e. the details page of a specific movie)
+- If dynamic routes are used, the App only loads what is needed, to keep memory usage low and the initial load time fast
+- Data provided in the URL hash can still be used to set the initial state of the App
+
+## Backtracking
+
+When a user enters your App via a deeplink, there is technically no history available. By default, this means that a Back keypress goes straight to
+the App's `root`-route (i.e. the `Blits.Application()`-component).
+
+In some cases, you may want walk back down the logical path of the deeplinked page instead, and navigate to the first existing parent route (i.e. go from `/movies/comedy/american-pie` to `/movies/comedy`).
+
+By setting the route option `backtrack` to `true` in the route definition (or in the `this.$router.to()`-method), the router will recursively remove the last part of the route hash, until it finds a valid path to navigate to.
+
+```js
+{
+  path: '/examples/router-hooks/episode/:id',
+  component: Episode,
+  transition: PageTransitions.slideInOutUp,
+  options: {
+    backtrack: true,
+  },
+},
+{
+  path: '/examples/router-hooks/episode',
+  component: EpisodesOverview,
+},
+```
+
+In the example above, the `backtrack` option is set to `true` for the `/examples/router-hooks/episode/:id` route. When the user navigates to `/examples/router-hooks/episode/1`, the `back` input action will navigate to `/examples/router-hooks/episode` instead of exiting the App.
+
 ## Router API
 
 The Router API provides several useful methods and properties for managing routes and navigation:

index.d.ts

@@ -783,12 +783,13 @@ declare module '@lightningjs/blits' {
      */
     canvas?: HTMLCanvasElement,
     /**
-     * The maximum number of textures to process in a single frame. This is used to
-     * prevent the renderer from processing too many textures in a single frame.
+     * The maximum amount of time the renderer is allowed to process textures in a
+     * single frame. If the processing time exceeds this limit, the renderer will
+     * skip processing the remaining textures and continue rendering the frame.
      *
-     * Defaults to `0` (meaning no limit)
+     * Defaults to `10`
      */
-    textureProcessingLimit?: number
+    textureProcessingTimeLimit?: number
   }
 
   interface State {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.17.1",
+  "version": "1.18.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.1.1",
-    "@lightningjs/renderer": "^2.9.1"
+    "@lightningjs/renderer": "^2.10.0"
   },
   "repository": {
     "type": "git",

src/components/RouterView.js

@@ -18,7 +18,7 @@
 import Component from '../component.js'
 import Router from '../router/router.js'
 
-let handler
+let hashchangeHandler = null
 
 export default () =>
   Component('RouterView', {
@@ -32,20 +32,21 @@ export default () =>
     },
     hooks: {
       ready() {
-        handler = () => Router.navigate.apply(this)
+        hashchangeHandler = () => Router.navigate.apply(this)
         Router.navigate.apply(this)
-        window.addEventListener('hashchange', handler)
+        window.addEventListener('hashchange', hashchangeHandler)
+
       },
       destroy() {
-        window.removeEventListener('hashchange', handler, false)
+        window.removeEventListener('hashchange', hashchangeHandler, false)
       },
       focus() {
         this.activeView && this.activeView.$focus()
       },
     },
     input: {
       back(e) {
-        const navigating = Router.back()
+        const navigating = Router.back.call(this)
         if (navigating === false) {
           this.parent.$focus(e)
         }

src/engines/L3/launch.js

@@ -66,7 +66,7 @@ export default (App, target, settings = {}) => {
       renderEngine: renderEngine(settings),
       fontEngines: textRenderEngines(settings),
       canvas: settings.canvas,
-      textureProcessingLimit: settings.textureProcessingLimit
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit
     },
     target
   )

src/router/router.js

@@ -320,9 +320,9 @@ export const to = (location, data = {}, options = {}) => {
   window.location.hash = `#${location}`
 }
 
-export const back = () => {
+export const back = function(){
   const route = history.pop()
-  if (route) {
+  if (route && currentRoute !== route) {
     // set indicator that we are navigating back (to prevent adding page to history stack)
     navigatingBack = true
     let targetRoutePath = route.path
@@ -333,9 +333,40 @@ export const back = () => {
     }
     to(targetRoutePath)
     return true
-  } else {
+  }
+
+  const backtrack = currentRoute && currentRoute.options.backtrack || false
+
+  // If we deeplink to a page without backtrack
+  // we we let the RouterView handle back
+  if(!backtrack){
+    return false
+  }
+
+  const hashEnd = /(\/:?[\w%\s-]+)$/
+  let path = currentRoute.path
+  let level = path.split('/').length
+
+  // On root return
+  if(level <= 1){
     return false
   }
+
+  while(level--){
+    if(!hashEnd.test(path)){
+      return false
+    }
+    // Construct new path to backtrack to
+    path = path.replace(hashEnd, '')
+    const route = matchHash(path, this.parent[symbols.routes])
+
+    if(route && backtrack){
+      to(route.path)
+      return true
+    }
+  }
+
+  return false
 }
 
 export default {