@lightningjs/blits 0.5.8 → 0.5.10

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+# v0.5.10
+
+_3 jan 2024_
+
+- Updated and improved documentation
+- Added `screenResolution` and `pixelRatio` options to settings
+
+# v0.5.9
+
+_21 dec 2023_
+
+- Changed transition-end callback to receive real prop value from node
+- Implemented symbol for `wrapper` on Component (freeing up the name wrapper to be used in Component state)
+- Added functionality to prevent a route ending up in the history stack (route option: `inHistory: false`)
+- Improved router backtracking logic
+- Added functionality to override route options during navigation
+- Upgraded to latest version of the renderer (0.6.1) which contains a fix for animations not finishing correctly
+
 # v0.5.8
 
 _15 dec 2023_

package/README.md

@@ -2,7 +2,7 @@
 
 # Blits - Lightning 3 App Development Framework
 
-With Blits (formaly know as Bolt), the App Development Framework for Lightning 3, it becomes a breeze to build great Lightning 3 applications.
+With Blits, the App Development Framework for Lightning 3, it becomes a breeze to build great Lightning 3 applications.
 
 Blits is built on top of the Lightning 3 Rendererer and aims to provide a **great developer experience**, making it fun and easy to build your apps!
 

package/boilerplate/package.json

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

package/docs/README.md

@@ -1,6 +1,6 @@
 # Blits - Lightning 3 App Development Framework
 
-With Blits (formerly know as Bolt), the App Development Framework for Lightning 3, it becomes a breeze to build great Lightning 3 applications.
+With Blits, the App Development Framework for Lightning 3, it becomes a breeze to build great Lightning 3 applications.
 
 Blits is built on top of the Lightning 3 Renderer and aims to provide a **great developer experience**, making it fun and easy to build your apps!
 
@@ -12,7 +12,9 @@ The Blits framework uses a **readable** XML-style template syntax and comes with
 
 You may be wondering where the name Blits comes from?
 
-Firstly, it short, memorable and has a nice ring to it. The name is derived from the word "Blitz", which means Lightning in German. Additionally, "Blits" is a Dutch term (a significant portion of the Lightning Open Source teams is based in the Netherlands) used to showcase something great or simply refer to things that are cool.
+Firstly, it's short, memorable and just has a nice ring to it.
+
+"Blits" is a Dutch word (a significant portion of the Lightning Open Source teams is based in the Netherlands). It means _flashy_ and it's often used to for things that are _great_ or _cool_.
 
 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 🙂
 
@@ -28,11 +30,12 @@ Finally it's a nerdy reference to the computer term "Bit Blits" commonly used in
 - [Computed properties](computed_properties.md)
 - [Watching for changes](watchers.md)
 - [Styling and positioning Elements](element_attributes.md)
+- [Displaying images](displaying_images.md)
+
 <!---
 - More complex logic in methods
 - Transitions
 - Implementing Custom components
 - Handling Text
-- Handling Images
 - Routing
 -->

package/docs/_sidebar.md

@@ -8,4 +8,5 @@
 - [Computed properties](computed_properties.md)
 - [Watching for changes](watchers.md)
 - [Styling and positioning Elements](element_attributes.md)
+- [Displaying images](displaying_images.md)
 

package/docs/component_state.md

@@ -2,20 +2,60 @@
 
 ## Component State
 
-In Blits, a component can start as simple as a template with fixed, hardcoded values. However, for dynamic behavior and logic, you'll often want to incorporate an internal state within your components.
+In Blits, a component can be as simple as a template with fixed, hardcoded values. However, for dynamic behavior and logic, you'll often want to extend your components with an _internal state_.
 
-Some key concepts to keep in mind:
+Some key concepts to keep in mind regarding Component state:
 
-- Each component instance maintains its own distinct internal state.
+- Each component _instance_ maintains its own distinct internal state.
 - The component state is defined within the `state` key of the Component configuration object.
-- The `state` is expected to be a `function`, a regular function (not an ES6 arrow function), that returns an object representing the component's state.
+- The `state` is expected to be a `function` (a regular function, not an ES6 arrow function), that returns an object representing the component's state.
 - The structure of the `state` object is flexible, allowing you to define state values according to your component's requirements. These values can range from `strings`, `booleans`, `arrays`, to even nested `objects`.
 - While flexibility in structuring your state is advantageous, be cautious about excessive nesting, as it could have a negative effect on performance.
 
 ### Accessing State in Templates
 
-As explained in the template section, you can refer to state variables in your Element's arguments by prefixing the state variable name with a dollar sign (e.g., `$alpha`). For nested objects, you can use dot notation (e.g., `$style.w`).
+As explained in the [template section](./template_syntax.md), you can refer to state variables in an Element's arguments by prefixing the state variable name with a _dollar sign_ (e.g., `$alpha`). For nested objects, you can use_dot notation_ (e.g., `$style.dimensions.w`).
 
 ### Accessing State in Component Code
 
-In your component's code, you can reference state variables within the `this` scope. For instance, a state variable named `color` can be accessed and modified by referencing `this.color`. It's important to note that unlike in the template, you should not use the dollar sign when accessing state variables within the component's code.
+In your component's code, you can reference state variables within the `this` scope. For instance, a state variable named `color` can be accessed and modified by referencing `this.color`. It's important to note that unlike in the template, you should _not_ use the dollar sign when accessing state variables within the component's code.
+
+```js
+export default Blits.Component('MyComponent', {
+  template: `
+    <Element :show="$active">
+      <Element :x="$style.x" w="100" :h="$style.dimensions.h">
+        <Element w="20" :h="$style.dimensions.h / 2" :color="$color" />
+      </Element>
+    </Element>
+  `,
+  state() {
+    return {
+      active: false,
+      items: [],
+      style: {
+        positions: {
+          x: 100,
+        },
+        dimensions: {
+          h: 100,
+        },
+      },
+      color: 'tomato'
+    }
+  }
+  hooks: {
+    ready() {
+      this.active = true
+      this.$setInterval(() => {
+        this.style.positions.x += 10
+      })
+    }
+  },
+  input: {
+    right() {
+      this.color = '#c0ffee'
+    }
+  }
+})
+```

package/docs/components.md

@@ -6,7 +6,6 @@ Components in Blits follow a clearly defined structure, which helps keep your co
 
 This universal structure is also valuable for the interoperability of components.
 
-
 ### Creating a new Component
 
 Let's see how to create a new component and explore the basic anatomy of a component.
@@ -15,13 +14,45 @@ A new component is created using the `Blits.Component()` function. This function
 
 1. The first argument is the name of the component, which is mainly used for debugging purposes. It's essential to choose a unique and descriptive name for your component, such as `Homepage`, `Loader` or `SidebarMenuItem`.
 
-2. The second argument is a configuration object, represented as an `object literal`. This configuration object can contain a predefined set of key-value pairs, including for example:
+2. The second argument is a _configuration object_, represented as an `object literal`. This configuration object can contain a predefined set of key-value pairs, including for example:
 
    - `template`: to define the template for the component.
    - `state`: to specify the component instance's internal state.
-   - `prop`: to define the props that can be passed into the component.
+   - `props`: to define the props that can be passed into the component.
    - `hooks`: allowing you to hook into different lifecycle events of the component.
    - `input`: used to tap into user input.
+   - `methods`: used to define more complex functionality of the component
+
+```js
+// src/components/Loader.js
+export default Blits('Loader', {
+  template: `
+    <Element x="880" y="500" :show="$active">
+      <Element x="$offset" w="40" h="40" color="#94a3b8" :alpha="$alpha" />
+    </Element>
+  `,
+  props: ['type', 'size'],
+  state() {
+    return {
+      active: false,
+      alpha: 0.4,
+      offset: 100
+    }
+  },
+  hooks: {
+    ready() {
+      this.$setTimeout(() => {
+        this.active = true
+      }, 300)
+    }
+  },
+  input: {
+    enter() {
+      this.alpha = 1
+    }
+  }
+})
+```
 
 In the next sections, we will go into the details of each of the component configuration options.
 

package/docs/displaying_images.md

@@ -0,0 +1,69 @@
+# Blits - Lightning 3 App Development Framework
+
+## Displaying Images
+
+
+Now that we've covered the basics of creating Elements, as well as styling and positioning them, it's time to move away from these boring rectangles and explore how you can incorporate _images_ into your App.
+
+In Blits is very easy to display an image. Simply add the `src` attribute to an Element, specifying the image's location.
+
+For local images, make sure to place them in the `public` folder (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (omitting the `public` folder as root).
+
+Remote images are also supported and can be linked directly (e.g., `http://mycdn.com/artists/jimi_hendrix/woodstock.jpg`).
+
+```xml
+<Element src="images/logo.png" w="100" h="80" />
+<Element src="http://mycdn.com/artists/jimi_hendrix/woodstock.jpg" w="1920" h="1080" />
+```
+
+### Sizing and Scaling
+
+Make sure to give your Element a width (`w` ) and a height (`h`) attribute. Blits will scale the image to fit these exact dimensions.
+
+For the best performance, it's important to keep your source images as small as possible. If you're displaying an image at `200px x 200px`, make sure the image is exactly that size or _smaller_. The latter option may lead to some quality loss.
+
+### Colorization
+
+You also have the option to _colorize_ an image on the fly. Just add a `color` attribute to the Element with a `src` attribute. You can use a single color, or apply a gradient. By default all Elements with a `src` attribute get the a solid white background, which corresponds with the actual colors of the image.
+
+```xml
+<Element
+  w="200"
+  h="300"
+  :src="$src"
+  color="{top: '#fff', bottom: '#000'}"
+/>
+```
+
+### Asynchronous Loading
+
+All images are loaded asynchronously (and can possibly fail to load), even those local to your App. Blits allows you to easily hook into the `loaded` and `error` events of image Elements.
+
+You can use this, for example, to only make something visible once an image is fully loaded. Or to display a fallback image when an remote image can't be retrieved.
+
+```xml
+<Element src="http://mycdn.com/lightning.jpg" @loaded="$revealPage" @error="$showFallback" />
+```
+
+> Note how events are prefixed with a `@` sign.
+
+Considering the template above, in the `methods` key of your Component configuration object, you would then do something like:
+
+```js
+{
+  //...
+  methods: {
+    revealPage(dimensions) {
+      this.$log.info('Image dimensions', dimensions.w, dimensions.h)
+      this.show = true
+    },
+    showFallback(error) {
+      this.$log.error('Image failed to load', error)
+      this.showBackupImage()
+    }
+  }
+}
+```
+
+The `loaded` event receives the images dimensions as it's argument and the `error` event receives an error message explaining the failure.
+

package/docs/element_attributes.md

@@ -92,7 +92,9 @@ The value of alpha is also being applied recursively to the children of the Elem
 
 ### Rotation and scaling
 
-If you want to rotate an Element, you can use the `rotation` attribute. The rotation attribute in Blits accepts values in degrees. The rotation of an Element is also automatically applied to any children down the tree.
+If you want to rotate an Element, you can use the `rotation` attribute. The rotation attribute in Blits accepts values in _degrees_.
+
+The rotation of an Element is also automatically applied to any children down the tree.
 
 ```xml
 <Element w="200" h="200" color="blue" rotation="90">
@@ -100,13 +102,20 @@ If you want to rotate an Element, you can use the `rotation` attribute. The rota
 </Element>
 ```
 
-For scaling an Element the `scale` attribute is used. This attribute can be any numeric value starting at `0`. The default value is `1`, which means no scaling. Any value below `1` will scale down the element and values greater than `1` will scale the element up.
+For scaling an Element the `scale` attribute is used.
+
+This attribute either accepts a single numeric value for scaling evenly accross width and height. Or an _object literal_, if you want to apply a different scaling for the `x` and the `y` axis.
+
+The value should start at `0` and the default value is `1`, which means no scaling.
+
+Any value below `1` will scale _down_ the element and values greater than `1` will scale the element _up_.
 
 Similar to rotation, scale is also applied recursively to children down the tree of the Element that has it's `scale` attribute set.
 
 ```xml
 <Element w="200" h="200" color="blue" scale="0.5" />
 <Element w="200" h="200" color="#000" scale="2.3" />
+<Element w="200" h="200" color="#000" scale="{x: 1, y: 3.14}" />
 ```
 
 ### Mounting point
@@ -119,20 +128,27 @@ In order to align the position starting at the _bottom-right_ corner, we would s
 
 If you omit either the `x` or the `y` key from the _object literal_, it's value will default to `0`.
 
+In the case where the `x` and `y` values are the same (i.e. centering with `{x: 0.5, y: 0.5}`), you can also just supply a single value (`mount="0.5"`) instead of the object literal notation.
+
 ```xml
 <Element w="200" h="200" x="20" y="100" color="#333" mount="{x: 0.5, y: 0.8}" />
 <Element w="200" h="200" x="800" y="400" color="#333" mount="{y: 1}" />
+<Element w="200" h="200" x="800" y="700" color="#333" mount="0.5" />
 ```
 
 ### Pivot point
 
-The pivot point of an Element comes into play when it's rotated or scaled. The pivot point defaults to the center of the Element, which means that when setting `rotation` it rotates around the middle. And when the Element is scaled it scales from the center out.
+The pivot point of an Element comes into play when it's rotated or scaled. The pivot point defaults to the _center_ of the Element, which means that when setting `rotation` it rotates around the middle. And when the Element is scaled it scales from the center out.
 
 But sometimes you may want rotate around the left corner, or scale from the right side out. This can be controlled by adding the `pivot` attribute to the Element and, similar to the `mount` attribute, specify an _object literal_ with a `x` and a `y` key.
 
 Both `y` and `x` values should be anything between `0` and `1`, where `{x: 0, y: 0}` sets the pivot point to the _top-left_ corner and `{x: 1, y: 1}` refers to the _bottom-right_ corner. The default pivot value is `{x: 0.5, y: 0.5}` (i.e. the center) and if you omit `x` or `y` in your pivot object, it will default to `0.5`.
 
+In the case where the `x` and `y` values are the same, you can also just supply a single value (`pivot="0.9"`) instead of the object literal notation.
+
+
 ```xml
 <Element w="200" h="200" x="20" y="100" pivot="{x: 0.5, y: 0.8}" rotation="69" />
 <Element w="200" h="200" x="800" y="400" pivot="{y: 1}" scale="3" />
+<Element w="200" h="200" x="800" y="700" pivot="0.9" rotation="42" />
 ```

package/docs/lifecycle_events.md

@@ -2,7 +2,7 @@
 
 ## Hooking into Lifecycle Events
 
-In Blits, components follow a defined flow of lifecycle events. Developers can integrate their logic into these events by specifying them in the `hooks` key of the Component configuration object.
+Blits components follow a defined flow of lifecycle events. You can integrate specific logic into these events by specifying them in the `hooks` key of the Component configuration object.
 
 For each available lifecycle event, you can define a function with the same name as the event itself. This function will execute each time the event is triggered for your component's instance. It's essential to use a regular function instead of an arrow function if you intend to access the `this` scope of your component instance.
 
@@ -18,11 +18,9 @@ For each available lifecycle event, you can define a function with the same name
 
 - **destroy()**: The `destroy` event fires when the component is being destroyed and removed. This event provides an opportunity to perform any custom cleanup operations before the component is removed.
 
-### Example
-
-```javascript
-{
-  // Other component configurations...
+```js
+export default Blits.Component('MyComponent', {
+  // ...
   hooks: {
     init() {
       // Logic to execute on init event
@@ -40,7 +38,5 @@ For each available lifecycle event, you can define a function with the same name
       // Logic to execute on destroy event
     },
   },
-};
+})
 ```
-
-In the provided example, each function within the `hooks` object corresponds to a specific lifecycle event, allowing developers to inject custom logic at different stages of the component's lifecycle.

package/docs/props.md

@@ -25,9 +25,11 @@ For more advanced usage, you can define props using an array of objects for each
 - Mark the prop as _required_.
 - Apply a `cast` function to modify the value passed as a prop.
 
-```javascript
-{
+```js
+export default Blits.Component('MyComponent', {
+  // ...
   props: [
+    'color',
     {
       key: 'alpha',
       default: 0.5,
@@ -38,7 +40,7 @@ For more advanced usage, you can define props using an array of objects for each
       cast: Number
     }
   ]
-}
+})
 ```
 
 You can mix and match the simple string notation with the more advanced object notation within the same `props` array.

package/docs/template_syntax.md

@@ -2,15 +2,13 @@
 
 ## Template structure
 
-Blits uses an easy-to-read XML-style template syntax. The syntax is inspired by frameworks like VueJS, so developers familiar with Vue will recognize certain concepts.
+Blits uses an easy-to-read _XML-style_ template syntax. The syntax is inspired by frameworks like VueJS, so developers familiar with Vue will recognize certain concepts.
 
-The template key in the configuration object holds a string with an XML-like structure. Templates often span multiple lines, so it's advisable to use a JS template literal.
+The _template_ key in the Componentn configuration object holds a string with an XML-like structure. Templates often span multiple lines, so it's advisable to use a JS template literal.
 
 You can use different tags in your templates. And similar to HTML you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported.
 
-The default tag within a template is the `<Element>` tag, which corresponds to a node in the Lightning 3 renderer. For each element, you can define a set of predefined render properties, such as `x`, `y`, `w`, `color`, and more. Detailed information regarding the properties supported by the <Element> tag can be found here.
-
-As your component grows in complexity, you may want to organize your template with custom components, abstracting both templates and logic. Inside a component template, you can utilize sub-components (i.e. a `Menu` component) and reference them with tags like `<Menu></Menu>`.
+The default tag within a template is the `<Element>` tag, which corresponds to a node in the Lightning 3 renderer. For each element, you can define a set of predefined render properties, such as `x`, `y`, `w`, `color`, and more. Detailed information regarding the attributes supported by the <Element> tag can be found [here](./element_attributes.md).
 
 Consider the following template example:
 
@@ -22,10 +20,46 @@ Consider the following template example:
 </Element>
 ```
 
+### Hardcoded arguments
+
 In this template, you'll observe certain arguments with hardcoded values. You use these to configure the parts of your component that never change.
 
+### Dynamic arguments
+
 Additionally, some arguments contain a value prefixed with a dollar sign (`$`), representing _dynamic_ arguments. When the component renders, it automatically populates these dynamic values based on the component's state (or props or computed properties).
 
+### Reactive arguments
+
 Furthermore, certain arguments are prefixed with a colon sign (`:`), indicating _reactive_ arguments. These are not only dynamically set when your component renders, but also _rerender_ the corresponding part of the template whenever the referenced value in your component's internal state changes. This reactive data binding eliminates the need for manual template patching, as seen in Lightning 2.
 
 Reactive arguments support _interpolation_, enabling the use of simple JavaScript instructions, such as ternary conditions or basic string and Math manipulations. For more complex logic, it's recommended to abstract this into a Component method or a Computed property.
+
+## Custom components
+
+As your component grows in complexity, you may want to reorganize your codebase with custom components, abstracting and reusing both templates and logic.
+
+Inside a component template, you can utilize sub-components (i.e. a `Menu` component) and reference them with tags like `<Menu></Menu>`.
+
+In order for the `<Menu />` tag to become available for use in a component's template, you first have to `import` the file that exports that component.
+
+Next you have to _register_ this imported component using the `components`-key in the configuration object. The `components` key is an _object literal_, where the value is the reference to the Blits component. The key will correspond with the _tag_ that can be used to invoke the component.
+
+```js
+
+import Menu from './components/menu.js'
+import Button from './components/button.js'
+
+export default Blits.Component('MyComponent', {
+  components: {
+    Menu, // makes <Menu /> available for use in the template
+    MyButton: Button, // makes Button available as <MyButton /> in the template
+  },
+  template: `
+    <Element>
+      <Menu />
+      <MyButton />
+    </Element>
+  `
+})
+
+```

package/docs/user_input.md

@@ -2,18 +2,25 @@
 
 ## Handling User Input
 
-You don't want your Lightning 3 App to be completely static, instead users should be able to navigate and interact with the app, often using devices like a remote control.
+When building an App you probably want users to interact with it as well, for example to enable them to navigate through your App. In other words, you will want to handle _user input_. In the context of a Blits / Lightning App this often will be key input via a remote control.
 
-Blits offers a straightforward interface to handle user input for each component.
+Blits offers an intuitive and straightforward interface to handle key input in components.
+
+### Focus
+
+Before diving into the specifics of key handling, it is important to understand the concept of _focus_. In a Blits app, there is always one Component that has the focus. By default this will be the root App component.
+
+The component that currently has focus, is the one that is responsible for handling the user input at that moment. For example, when a user clicks the _right_ or _left_ button while a _Poster Component_ has focus, it is that instance of the Poster Component that will initially _receive_ the key press event.
 
 ### Configuring Input Handling
 
-Within the Component configuration object, the `input` key is utilized to define how the component should react to specific key presses when it has focus. It should contain an object of functions that specify the actions to take based on key presses.
+Within the Component configuration object, the `input` key is used to define how the component should react to specific key presses when it has focus. The `input` key should be an `object literal` of `functions` for each input event that the component wants to handle.
 
-Each function should correspond to a key name, such as `up`, `down`, `enter`, `space`, `back`, `1`, `2`, `a` etc. Each function defined in the `input` object receives the full `InputEvent` object as its first argument.
+Each function corresponds to a _key name_, such as `up`, `down`, `enter`, `space`, `back`, `1`, `2`, `a` etc. Each function defined in the `input` object, receives the full `InputEvent` object as its first argument.
 
 ```javascript
-{
+export default Blits.Component('MyComponent', {
+  // ...
   input: {
     up() {
       // Logic to execute when users press up
@@ -30,9 +37,9 @@ Each function should correspond to a key name, such as `up`, `down`, `enter`, `s
 
 ### Event Handling Chain
 
-If the currently focused component does not handle a key press, the framework will traverse up the component hierarchy, checking if any parent components have defined functions for that key press in their `input`-object. This event handling chain continues until it reaches the root Application.
+If the currently focused component does not handle a key press, Blits will traverse up the component hierarchy, checking for any _parent_ component that does have a function defined for that key press in the `input`-key. This input event handling chain continues until it reaches the root App component.
 
-When a component handles a key press by having a corresponding function specified, the event handling chain stops by default. However, if you want the input event to propagate up the hierarchy, you can set focus to the parent element and pass the `InputEvent` object on in the function call.
+When a component handles a key press by having a corresponding function specified, the event handling chain stops by default. However, if you want the input event to propagate up the hierarchy, you can set focus to the parent element and pass the `InputEvent` object on in that function call.
 
 ```javascript
 {
@@ -51,7 +58,7 @@ When a component handles a key press by having a corresponding function specifie
 
 ### Catch-All Handling
 
-To allow a focused component to respond to any key and act as a catch-all, you can add an `any()` function to the input object.
+To allow a focused component to respond to any key and act as a _catch-all_, you can add an `any()` function to the input object.
 
 ```javascript
 {
@@ -62,3 +69,59 @@ To allow a focused component to respond to any key and act as a catch-all, you c
   }
 }
 ```
+
+### Custom Keycode mapping
+
+Blits comes with a default keycode mapping. This mapping is a sensible default that works in your desktop browser and with most RDK based devices.
+
+But it's possible that the keycodes and mapping of your target device are slightly or even completely different.
+
+In Blits you can easily configure the key mapping to match your needs. In the `src/index.js` file where we instaniate the App via the `Blits.Launch` function, we can add an extra key, called `keys`, to the _settings object_.
+
+The `'key` item should be an object literal with _key value pairs_. As the `key`, you should provide the `key` or `keyCode` of the `KeyboardEvent` and the `value` should be the name of the event as used in the `input` object of the Component configuration object.
+
+> You can use a site like [keyjs.dev](https://keyjs.dev/) to find the key and keyCode
+
+```js
+// src/index.js
+Blits.Launch(App, 'app', {
+  w: 1920,
+  h: 1080,
+  //...
+  keys: {
+    // switch left and right using the key
+    ArrowLeft: 'right',
+    ArrowRight: 'left',
+    // switch up and down using the keyCode
+    38: 'down',
+    40: 'up',
+    // register new handlers
+    '.': 'dot', // dot() can now be used in the input object
+    // key code for letter 's'
+    83: 'search' // search() can now be used in the input object
+  }
+})
+```
+
+The custom keys object will be merged with the default key mapping, that looks like this:
+
+```js
+const defaultKeyMap = {
+  ArrowLeft: 'left',
+  ArrowRight: 'right',
+  ArrowUp: 'up',
+  ArrowDown: 'down',
+  Enter: 'enter',
+  ' ': 'space',
+  Backspace: 'back',
+  Escape: 'escape',
+  37: 'left',
+  39: 'right',
+  38: 'up',
+  40: 'down',
+  13: 'enter',
+  32: 'space',
+  8: 'back',
+  27: 'escape',
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.cjs",
   "exports": {
@@ -42,7 +42,7 @@
     "tape": "^5.5.0"
   },
   "dependencies": {
-    "@lightningjs/renderer": "^0.6.0",
+    "@lightningjs/renderer": "^0.6.1",
     "@lightningjs/vite-plugin-import-chunk-url": "^0.3.0"
   }
 }

package/src/component.js

@@ -121,7 +121,7 @@ const Component = (name = required('name'), config = required('config')) => {
     }
 
     this.parent = parentComponent
-    this.wrapper = parentEl
+    this[symbols.wrapper] = parentEl
 
     Object.defineProperties(this, {
       type: {

package/src/element.js

@@ -163,7 +163,7 @@ const Props = {
     this._set.add('scale')
   },
   set show(v) {
-    this.alpha = v ? 1 : 0
+    this._props.alpha = v ? 1 : 0
   },
   set alpha(v) {
     this._props.alpha = v
@@ -317,7 +317,7 @@ const Element = {
                 // fire transition end callback if specified
                 transition.end &&
                   typeof transition.end === 'function' &&
-                  transition.end.call(this.component, this, prop, props[prop])
+                  transition.end.call(this.component, this, prop, this.node[prop])
               })
               .then(resolve)
           } catch (e) {

package/src/launch.d.ts

@@ -51,6 +51,8 @@ interface SdfFont {
   png: string
 }
 
+type ScreenResolutions = 'hd' | '720p' | 720 | 'fhd' | 'fullhd' | '1080p' | 1080 | '4k' | '2160p' | 2160
+
 type Font = WebFont | SdfFont
 
 export type DebugLevel = 0 | 1 | 2
@@ -95,7 +97,45 @@ export interface Settings {
   /**
    * Mode of reactivity (`Proxy` or `defineProperty`)
    */
-  reactivityMode?: ReactivityModes
+  reactivityMode?: ReactivityModes,
+  /**
+  * Screen resolution of the device, defining the pixelRatio used to convert dimensions
+  * and positions in the App code to the actual device logical coordinates
+  *
+  * If not supplied, Blits will try to autodetect the device screen resolution. Otherwise
+  * the exact dimensions and positions used the app code are used.
+  *
+  * Note: If the option `pixelRatio` is specified in the Settings object, this value will take presedence
+  * over the screen resolution setting.
+  *
+  * Currently 3 screen resolutions are supported, which can be defined with different alias values:
+  *
+  * For 720x1080 (1px = 0.66666667px)
+  * - hd
+  * - 720p
+  * - 720
+  *
+  * For 1080x1920 (1px = 1px)
+  * - fhd
+  * - fullhd
+  * - 1080p
+  * - 1080
+  *
+  * For 2160x3840 (1px = 2px)
+  * - 4k
+  * - 2160p
+  * - 2160
+  */
+  screenResolution?: ScreenResolutions,
+  /**
+  * Custom pixel ratio of the device used to convert dimensions
+  * and positions in the App code to the actual device logical coordinates
+  *
+  * Takes presedence over the `screenResolution` setting
+  *
+  * Defaults to 1 if not specified
+  */
+  pixelRatio?: number
 }
 
 /**

package/src/launch.js

@@ -19,7 +19,7 @@ import { MainCoreDriver, RendererMain } from '@lightningjs/renderer'
 // import RendererWorker from '@lightningjs/renderer/workers/renderer?worker'
 import Settings from './settings.js'
 import { initLog, Log } from './lib/log.js'
-
+import { screenResolutions } from './lib/utils.js'
 // import coreExtensionModule from './fontLoader.js?importChunkUrl'
 
 export let renderer
@@ -41,6 +41,11 @@ export default (App, target, settings) => {
       appWidth: settings.w || 1920,
       appHeight: settings.h || 1080,
       coreExtensionModule: settings.fontLoader,
+      deviceLogicalPixelRatio:
+        settings.pixelRatio ||
+        screenResolutions[settings.screenResolution] ||
+        screenResolutions[window.innerHeight] ||
+        1,
     },
     target,
     driver

package/src/lib/setup/routes.js

@@ -21,6 +21,17 @@ export default (component, routes) => {
   component.prototype[symbols.routes] = []
   Object.keys(routes).forEach((key) => {
     // todo: validate routes[key] for expected format etc.
-    component.prototype[symbols.routes][key] = routes[key]
+    component.prototype[symbols.routes][key] = {
+      ...routes[key],
+      ...{
+        // merge default route options with route specific options
+        options: {
+          ...{
+            inHistory: true,
+          },
+          ...routes[key].options,
+        },
+      },
+    }
   })
 }

package/src/lib/symbols.js

@@ -23,6 +23,7 @@ export default {
   type: Symbol('type'),
   watchers: Symbol('watchers'),
   watchKeys: Symbol('watchKeys'),
+  wrapper: Symbol('wrapper'),
 
   /* Utilizing the global Symbol registry for the following purposes */
 

package/src/lib/utils.js

@@ -0,0 +1,12 @@
+export const screenResolutions = {
+  hd: 0.66666667,
+  '720p': 0.66666667,
+  720: 0.66666667,
+  fhd: 1,
+  fullhd: 1,
+  '1080p': 1,
+  1080: 1,
+  '4k': 2,
+  '2160p': 2,
+  2160: 2,
+}

package/src/router/router.js

@@ -27,6 +27,8 @@ export let navigating = false
 
 const cacheMap = new WeakMap()
 const history = []
+let overrideOptions = {}
+let navigatingBack = false
 
 export const getHash = () => {
   return (document.location.hash || '/').replace(/^#/, '')
@@ -38,7 +40,10 @@ export const matchHash = (path, routes = []) => {
       return r.path === path
     })
     .pop()
-  if (route) currentRoute = route
+  if (route) {
+    route.options = { ...route.options, ...overrideOptions }
+    currentRoute = route
+  }
   return route
 }
 
@@ -50,7 +55,11 @@ export const navigate = async function () {
     const route = matchHash(hash, this.parent[symbols.routes])
 
     if (route) {
-      if (history[history.length - 1] !== hash) history.push(hash)
+      // add the previous route (tecnhically still the current route at this point)
+      // into the history stack, unless navigating back or inHistory flag of route is false
+      if (navigatingBack === false && previousRoute && previousRoute.options.inHistory === true) {
+        history.push(previousRoute)
+      }
       // apply default transition if none specified
       if (!('transition' in route)) {
         route.transition = fadeInFadeOutTransition
@@ -82,7 +91,7 @@ export const navigate = async function () {
           view = view(this[symbols.props], holder, this)
         }
       } else {
-        holder = view.wrapper
+        holder = view[symbols.wrapper]
       }
 
       this[symbols.children].push(view)
@@ -130,6 +139,9 @@ export const navigate = async function () {
       Log.error(`Route ${hash} not found`)
     }
   }
+
+  // reset navigating indicators
+  navigatingBack = false
   navigating = false
 }
 
@@ -139,11 +151,11 @@ const removeView = async (route, view, transition) => {
     if (Array.isArray(transition)) {
       for (let i = 0; i < transition.length; i++) {
         i === transition.length - 1
-          ? await setOrAnimate(view.wrapper, transition[i])
-          : setOrAnimate(view.wrapper, transition[i])
+          ? await setOrAnimate(view[symbols.wrapper], transition[i])
+          : setOrAnimate(view[symbols.wrapper], transition[i])
       }
     } else {
-      await setOrAnimate(view.wrapper, transition)
+      await setOrAnimate(view[symbols.wrapper], transition)
     }
   }
 
@@ -169,14 +181,17 @@ const setOrAnimate = (node, transition, shouldAnimate = true) => {
     : node.set(transition.prop, transition.value)
 }
 
-export const to = (location) => {
+export const to = (location, options = {}) => {
+  overrideOptions = options
   window.location.hash = `#${location}`
 }
 
 export const back = () => {
-  if (history.length > 1) {
-    to(history[history.length - 2])
-    history.splice(-2, 2)
+  const route = history.pop()
+  if (route) {
+    // set indicator that we are navigating back (to prevent adding page to history stack)
+    navigatingBack = true
+    to(route.path)
     return true
   } else {
     return false