@lightningjs/blits 1.30.1 → 1.30.2

package/docs/components/watchers.md

@@ -1,34 +1,34 @@
-# Watchers
-
-In some cases, you may want to execute specific actions whenever the value of a state variable, a prop, or a computed property changes. These actions could involve dispatching an event or updating another state variable.
-
-You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into an endless loop.
-
-Instead, Blits allows you to specify **watchers** to trigger functionality when certain variables change.
-
-## Using Watchers
-
-Within the `watch` key of the _Component configuration object_, you can define an object of _watcher functions_.
-
-The name of each function should correspond with the name of the state variable, the prop, or the computed property that you want to observe. Whenever the value of the observed target changes, the respective watcher function will be invoked.
-
-The watcher function receives two arguments: the _new value_ and the _old value_ of the observed property. This allows you to perform specific actions based on the changes.
-
-```javascript
-{
-  state() {
-    return {
-      alpha: 0.2
-    }
-  },
-  watch: {
-    alpha(value, oldValue) {
-      if(value > oldValue) {
-        // Execute some logic when the 'alpha' value increases
-      }
-    },
-  }
-}
-```
-
-In this example, whenever the value of state variable `alpha` changes, the `alpha` watcher function will be invoked. The function checks if the new value is greater than the old value and executes custom logic accordingly.
+# Watchers
+
+In some cases, you may want to execute specific actions whenever the value of a state variable, a prop, or a computed property changes. These actions could involve dispatching an event or updating another state variable.
+
+You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into an endless loop.
+
+Instead, Blits allows you to specify **watchers** to trigger functionality when certain variables change.
+
+## Using Watchers
+
+Within the `watch` key of the _Component configuration object_, you can define an object of _watcher functions_.
+
+The name of each function should correspond with the name of the state variable, the prop, or the computed property that you want to observe. Whenever the value of the observed target changes, the respective watcher function will be invoked.
+
+The watcher function receives two arguments: the _new value_ and the _old value_ of the observed property. This allows you to perform specific actions based on the changes.
+
+```javascript
+{
+  state() {
+    return {
+      alpha: 0.2
+    }
+  },
+  watch: {
+    alpha(value, oldValue) {
+      if(value > oldValue) {
+        // Execute some logic when the 'alpha' value increases
+      }
+    },
+  }
+}
+```
+
+In this example, whenever the value of state variable `alpha` changes, the `alpha` watcher function will be invoked. The function checks if the new value is greater than the old value and executes custom logic accordingly.

package/docs/essentials/application_root.md

@@ -1,19 +1,19 @@
-# Application root
-
-Every Blits App starts with a base Application component.
-
-Ultimately this Application is a component like any regular Blits component. But it is augmented with some extra functionality. `Blits.Application` is responsible for setting up the listeners for keyhandling for example.
-
-You can only have 1 Application component per App. By default, this file is named `App.js` and it is placed in the root of the `src`-folder.
-
-`src/App.js` will look something like this:
-
-```js
-import Blits from '@lightningjs/blits'
-
-export default Blits.Application({
-  template: `
-    <Element></Element>
-   `,
-})
-```
+# Application root
+
+Every Blits App starts with a base Application component.
+
+Ultimately this Application is a component like any regular Blits component. But it is augmented with some extra functionality. `Blits.Application` is responsible for setting up the listeners for keyhandling for example.
+
+You can only have 1 Application component per App. By default, this file is named `App.js` and it is placed in the root of the `src`-folder.
+
+`src/App.js` will look something like this:
+
+```js
+import Blits from '@lightningjs/blits'
+
+export default Blits.Application({
+  template: `
+    <Element></Element>
+   `,
+})
+```

package/docs/essentials/components.md

@@ -1,68 +1,68 @@
-# Components
-
-Like any modern front-end framework, Blits is built around the concept of Components. Components allow you to split the UI of your App into
-reusable pieces of code and logic.
-
-As you get started building your App, you're free to put all your elements and logic right in the root Application component.
-This is great for quickly playing around with Blits and Lightning.
-
-But soon you'll find that it's beneficial to start organizing the different parts of your App into separate components. Blits Components can be nested into a tree of components.
-
-Components in Blits follow a clearly defined structure, which helps keep your code clean and guides you to quickly build your components.
-
-This universal structure is also valuable for creating drop-in components that can be easily shared across projects.
-
-## Creating a new Component
-
-Let's see how to create a new component and explore the basic anatomy of a component.
-
-A new component is created using the `Blits.Component()` function that is exported from the `@lightningjs/blits` package. This function accepts two arguments:
-
-- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader`, or `SidebarMenuItem`.
-
-- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that define how your Component looks and behaves.
-
-Some of the commonly used Component configuration options include:
-
-   - `template`: to define the template for the component.
-   - `state`: to specify the component instance's internal state.
-   - `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
-
-A basic Blits component will then look something like this:
-
-```js
-// src/components/Loader.js
-export default Blits.Component('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.
-
+# Components
+
+Like any modern front-end framework, Blits is built around the concept of Components. Components allow you to split the UI of your App into
+reusable pieces of code and logic.
+
+As you get started building your App, you're free to put all your elements and logic right in the root Application component.
+This is great for quickly playing around with Blits and Lightning.
+
+But soon you'll find that it's beneficial to start organizing the different parts of your App into separate components. Blits Components can be nested into a tree of components.
+
+Components in Blits follow a clearly defined structure, which helps keep your code clean and guides you to quickly build your components.
+
+This universal structure is also valuable for creating drop-in components that can be easily shared across projects.
+
+## Creating a new Component
+
+Let's see how to create a new component and explore the basic anatomy of a component.
+
+A new component is created using the `Blits.Component()` function that is exported from the `@lightningjs/blits` package. This function accepts two arguments:
+
+- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader`, or `SidebarMenuItem`.
+
+- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that define how your Component looks and behaves.
+
+Some of the commonly used Component configuration options include:
+
+   - `template`: to define the template for the component.
+   - `state`: to specify the component instance's internal state.
+   - `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
+
+A basic Blits component will then look something like this:
+
+```js
+// src/components/Loader.js
+export default Blits.Component('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/essentials/displaying_images.md

@@ -1,67 +1,67 @@
-# 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, it 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 of your App (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (but 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. Images will _not_ be rendered if they don't have both attributes present. The Lightning renderer 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, but can positively impact the overall performance of your App.
-
-## 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 a solid white background, with the result that the actual colors of the image will be shown.
-
-```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 a 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 you would do something like the following in the `methods` key of your Component configuration object:
-
-```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 image dimensions as its argument and the `error` event receives an error message explaining the failure.
+# 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, it 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 of your App (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (but 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. Images will _not_ be rendered if they don't have both attributes present. The Lightning renderer 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, but can positively impact the overall performance of your App.
+
+## 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 a solid white background, with the result that the actual colors of the image will be shown.
+
+```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 a 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 you would do something like the following in the `methods` key of your Component configuration object:
+
+```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 image dimensions as its argument and the `error` event receives an error message explaining the failure.