@lightningjs/blits 1.30.1 → 1.30.2

package/docs/performance/lazy-loading.md

@@ -1,161 +1,161 @@
-# Lazy Loading with the :range Parameter
-
-The for-loop in Blits comes with a [`:range` parameter](../built-in/for-loop.html#using-the-range-attribute) that allows you to render only a portion of an array rather than all the items.
-
-This `:range` parameter can also be used to easily implement an efficient form of _lazy loading_. Lazy loading is a crucial concept for performance in TV applications where rails can contain hundreds of items, but only a small subset is visible at any time.
-
-## Basic range implementation
-
-For the basic syntax of the `:range` attribute, we typically set dynamic `from` and `to` values, which define the subset of items to display.
-
-```js
-<Tile :for="(item, index) in $items" :range="{from: $from, to: $to}" />
-```
-
-A full example of a Rail component with a range would look something like this:
-
-```js
-export default Blits.Component('RangedRail', {
-  template: `
-    <Element :x.transition="0 - $focused * 300">
-      <Tile
-        :for="(item, index) in $items"
-        :range="{from: $range, to: $range + 7}"
-        :key="$item.id"
-        :focused="$focused"
-        w="300"
-        h="200"
-        :x="$index * 320"
-      />
-    </Element>
-  `,
-  state() {
-    return {
-      range: 0,
-      focused: 0,
-      items: [] // Array of 100+ items
-    }
-  },
-  input: {
-    right() {
-      this.focus = Math.min(this.focus + 1, items.length)
-      this.range++
-    },
-    left() {
-      this.focus = Math.max(this.focus - 1, 0)
-      this.range--
-    }
-  }
-})
-```
-
-Benefits of this approach are:
-
-- **Selective Rendering**: Only items within the specified range are actually created as elements
-- **Performance Optimization**: Reduces memory usage and improves rendering performance
-- **Dynamic Range Updates**: The range can be computed based on user interaction and scroll position
-
-A downside of this approach is that, as we scroll we are also **destroying** components that are out of range. And we may need those
-same items when we scroll back (and thus recreate them). On top of that, destroying Components and Elements also comes at a cost.
-
-## Lazy loading with the range attribute
-
-We can solve the problem of destroying Components that we may want to use again by slightly changing the logic of the Rail component.
-
-1) We set `from: 0`, to ensure we always start from the first item (and _keep_ the first items)
-2) We use `to: $range + 7`  to render up to the current position plus a lookahead buffer
-3) The `$range` value tracks how far the user has navigated through the rail, but it doesn't decrement when navigating back
-
-With these changes a full example of a LazyRail component would look something like this:
-
-```js
-export default Blits.Component('LazyRail', {
-  template: `
-    <Element :x.transition="0 - $focused * 300">
-      <Tile
-        :for="(item, index) in $items"
-        :range="{from: 0, to: $range + 7}"
-        :key="$item.id"
-        w="300"
-        h="200"
-        :x="$index * 320"
-      />
-    </Element>
-  `,
-  state() {
-    return {
-      range: 0,
-      items: [] // Array of 100+ items
-    }
-  },
-  input: {
-    right() {
-      this.focus = Math.min(this.focus + 1, items.length)
-      // push the range update to the next tick to spread out the work
-      // and ease the CPU a bit
-      this.$setTimeout(() => this.range = this.focus)
-
-    },
-    left() {
-      this.focus = Math.max(this.focus - 1, 0)
-      // we don't decrement the range when scrolling back to keep components alive
-      // this.range--
-    }
-  }
-})
-```
-
-## Performance Benefits
-
-Properly applying the range attribute provides **Memory Efficiency**:
-
-- Instead of creating 100+ elements, only ~8-15 are active
-- Reduces GPU memory usage on constrained TV hardware
-- Lower overall memory footprint
-
-It also is beneficial for **Faster Rendering**
-
-- Initial page load only renders visible items
-- Scroll performance improves as fewer elements need updates
-- Reduced layout calculations
-
-
-It **optimizes bandwidth**
-
-- Images and assets only load for rendered items
-- Reduces network requests on page load
-- Progressive content loading
-
-
-### Alpha Transitions
-
-For a smoother experience you consider applying an alpha transition, that fades out items at the end of the rang.e
-
-```js
-:alpha.transition="$index <= $range ? 1 : ($index <= $range + 3 ? 0.8 : 0.6)"
-```
-
-This creates a dimming effect for previously viewed items while maintaining full opacity for the current and upcoming items.
-
-## Best Practices
-
-### Buffer Size
-
-Use a buffer of 5-10 items ahead of current position:
-
-```js
-// Conservative buffer for low-end devices
-:range="{from: $currentIndex - 1, to: $currentIndex + 6}"
-
-// Larger buffer for smoother experience
-:range="{from: $currentIndex - 2, to: $currentIndex + 10}"
-```
-
-## Performance Impact
-
-On typical TV hardware:
-
-- **Memory Usage**: 70-80% reduction compared to full rendering
-- **Initial Load Time**: 3-5x faster page initialization
-- **Scroll Performance**: Consistent fps maintained vs potential frame drops
-- **Network Requests**: Reduced by 80-90% on initial load
+# Lazy Loading with the :range Parameter
+
+The for-loop in Blits comes with a [`:range` parameter](../built-in/for-loop.html#using-the-range-attribute) that allows you to render only a portion of an array rather than all the items.
+
+This `:range` parameter can also be used to easily implement an efficient form of _lazy loading_. Lazy loading is a crucial concept for performance in TV applications where rails can contain hundreds of items, but only a small subset is visible at any time.
+
+## Basic range implementation
+
+For the basic syntax of the `:range` attribute, we typically set dynamic `from` and `to` values, which define the subset of items to display.
+
+```js
+<Tile :for="(item, index) in $items" :range="{from: $from, to: $to}" />
+```
+
+A full example of a Rail component with a range would look something like this:
+
+```js
+export default Blits.Component('RangedRail', {
+  template: `
+    <Element :x.transition="0 - $focused * 300">
+      <Tile
+        :for="(item, index) in $items"
+        :range="{from: $range, to: $range + 7}"
+        :key="$item.id"
+        :focused="$focused"
+        w="300"
+        h="200"
+        :x="$index * 320"
+      />
+    </Element>
+  `,
+  state() {
+    return {
+      range: 0,
+      focused: 0,
+      items: [] // Array of 100+ items
+    }
+  },
+  input: {
+    right() {
+      this.focus = Math.min(this.focus + 1, items.length)
+      this.range++
+    },
+    left() {
+      this.focus = Math.max(this.focus - 1, 0)
+      this.range--
+    }
+  }
+})
+```
+
+Benefits of this approach are:
+
+- **Selective Rendering**: Only items within the specified range are actually created as elements
+- **Performance Optimization**: Reduces memory usage and improves rendering performance
+- **Dynamic Range Updates**: The range can be computed based on user interaction and scroll position
+
+A downside of this approach is that, as we scroll we are also **destroying** components that are out of range. And we may need those
+same items when we scroll back (and thus recreate them). On top of that, destroying Components and Elements also comes at a cost.
+
+## Lazy loading with the range attribute
+
+We can solve the problem of destroying Components that we may want to use again by slightly changing the logic of the Rail component.
+
+1) We set `from: 0`, to ensure we always start from the first item (and _keep_ the first items)
+2) We use `to: $range + 7`  to render up to the current position plus a lookahead buffer
+3) The `$range` value tracks how far the user has navigated through the rail, but it doesn't decrement when navigating back
+
+With these changes a full example of a LazyRail component would look something like this:
+
+```js
+export default Blits.Component('LazyRail', {
+  template: `
+    <Element :x.transition="0 - $focused * 300">
+      <Tile
+        :for="(item, index) in $items"
+        :range="{from: 0, to: $range + 7}"
+        :key="$item.id"
+        w="300"
+        h="200"
+        :x="$index * 320"
+      />
+    </Element>
+  `,
+  state() {
+    return {
+      range: 0,
+      items: [] // Array of 100+ items
+    }
+  },
+  input: {
+    right() {
+      this.focus = Math.min(this.focus + 1, items.length)
+      // push the range update to the next tick to spread out the work
+      // and ease the CPU a bit
+      this.$setTimeout(() => this.range = this.focus)
+
+    },
+    left() {
+      this.focus = Math.max(this.focus - 1, 0)
+      // we don't decrement the range when scrolling back to keep components alive
+      // this.range--
+    }
+  }
+})
+```
+
+## Performance Benefits
+
+Properly applying the range attribute provides **Memory Efficiency**:
+
+- Instead of creating 100+ elements, only ~8-15 are active
+- Reduces GPU memory usage on constrained TV hardware
+- Lower overall memory footprint
+
+It also is beneficial for **Faster Rendering**
+
+- Initial page load only renders visible items
+- Scroll performance improves as fewer elements need updates
+- Reduced layout calculations
+
+
+It **optimizes bandwidth**
+
+- Images and assets only load for rendered items
+- Reduces network requests on page load
+- Progressive content loading
+
+
+### Alpha Transitions
+
+For a smoother experience you consider applying an alpha transition, that fades out items at the end of the rang.e
+
+```js
+:alpha.transition="$index <= $range ? 1 : ($index <= $range + 3 ? 0.8 : 0.6)"
+```
+
+This creates a dimming effect for previously viewed items while maintaining full opacity for the current and upcoming items.
+
+## Best Practices
+
+### Buffer Size
+
+Use a buffer of 5-10 items ahead of current position:
+
+```js
+// Conservative buffer for low-end devices
+:range="{from: $currentIndex - 1, to: $currentIndex + 6}"
+
+// Larger buffer for smoother experience
+:range="{from: $currentIndex - 2, to: $currentIndex + 10}"
+```
+
+## Performance Impact
+
+On typical TV hardware:
+
+- **Memory Usage**: 70-80% reduction compared to full rendering
+- **Initial Load Time**: 3-5x faster page initialization
+- **Scroll Performance**: Consistent fps maintained vs potential frame drops
+- **Network Requests**: Reduced by 80-90% on initial load

package/docs/plugins/global_app_state.md

@@ -1,98 +1,98 @@
-# Global App State plugin
-
-Each Blits Component has its own, internal component state that is reactive and can automatically trigger updates in the template upon changes. The internal state is fully encapsulated, which ensures predictable component state and promotes a pattern of clear separation of concerns.
-
-But a Component usually doesn't live on its own, instead it's part of a bigger App. And there may arise a need for components to exchange data - intercomponent communication in other words.
-
-Blits offers the option to _emit_ and _listen_ to events, as explained in the section on Blits [utility methods](../components/utility_methods.md). For simple use cases, this is a convenient method to pass data along. But when used extensively, it may be easy to lose track of data flows.
-
-For more advanced cases, Blits offers an optional Global App State plugin that will act as a global state store that all components have direct access to. It's a simple implementation, focused on providing a _performant_ and _easy to use_ solution for global state. It's not a full flux / redux style state management solution, as we know from experience that these solutions (while very useful and cool), may lead to performance issues on low-end devices.
-
-## Registering the plugin
-
-The Global App state plugin is provided in the core Blits package, but as it's an _optional_ plugin it first needs to be registered.
-
-The plugin can be imported from Blits and registered in the App's `index.js`, as demonstrated in the example below.
-
-Make sure to place the `Blits.Plugin()` method _before_ calling the `Blits.Launch()` method.
-
-```js
-// index.js
-
-import Blits from '@lightningjs/blits'
-// import the app state plugin
-import { appState } from '@lightningjs/blits/plugins'
-
-import App from './App.js'
-
-// Use the Blits App State plugin
-Blits.Plugin(appState, {
-  loggedIn: false,
-  user: {
-    id: null,
-    name: '',
-    lastname: ''
-  },
-  languages: ['en', 'nl', 'pt', 'es'],
-})
-
-
-Blits.Launch(App, 'app', {
-  // launch settings
-})
-```
-
-### State object
-
-When registering the Global App State plugin, you pass it a state object as the second argument. This is a plain object literal that will be converted into a _reactive_ object, and is used to keep track of the global state variables.
-
-The newly created Global App state works exactly the same as an internal Component state. You can read values and you can directly change values. And when you do change a value, it automatically triggers reactive updates. Either via reactive attributes in the template, or in the form of watchers / computed values in the Component logic.
-
-### Using global app state in a Component
-
-Any variable in the Global App state can be used directly in the template, much like a local Component state. Changing values in the global app state also works exactly the same as updating the internal component state.
-
-```js
-Blits.Component('MyComponent', {
-  template: `
-    <Element>
-      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
-    </Element>
-  `,
-  input: {
-    enter() {
-      this.$appState.user.name = 'John'
-      this.$appState.loggedIn = true
-    }
-  },
-})
-```
-
-Note that in the template definition, 2 consecutive dollars signs are used (`$$appState`). The first `$`-sign is used
-to refer to the Component scope, as with any other state variable or computed property referenced in the template.
-
-The second `$`-sign is needed, since the appState plugin itself is prefixed with a dollar sign, to prevent accidental naming collisions.
-
-In order to read or update variables on the global app state inside the component logic, you can access the entire state via `this.$appState`.
-
-### Watching global state
-
-Similar to component state, you can watch for changes in the global state as well. You can refer to global state variables using _dot-notation_ in the watcher function name, and _prefixing_ it with `$appState`. This means that you need to define your watcher as a `String`, matching one of the examples below, depending on your style preference.
-
-```js
-Blits.Component('MyComponent', {
-  template: `
-    <Element>
-      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
-    </Element>
-  `,
-  watch: {
-    '$appState.fooBar'(v, old) {
-      console.log(`$appState.fooBar changed from ${old} to ${v}`)
-    },
-    '$appState.my.nested.data': function(v, old) {
-      console.log(`My nested App state data changed!`)
-    }
-  },
-})
-```
+# Global App State plugin
+
+Each Blits Component has its own, internal component state that is reactive and can automatically trigger updates in the template upon changes. The internal state is fully encapsulated, which ensures predictable component state and promotes a pattern of clear separation of concerns.
+
+But a Component usually doesn't live on its own, instead it's part of a bigger App. And there may arise a need for components to exchange data - intercomponent communication in other words.
+
+Blits offers the option to _emit_ and _listen_ to events, as explained in the section on Blits [utility methods](../components/utility_methods.md). For simple use cases, this is a convenient method to pass data along. But when used extensively, it may be easy to lose track of data flows.
+
+For more advanced cases, Blits offers an optional Global App State plugin that will act as a global state store that all components have direct access to. It's a simple implementation, focused on providing a _performant_ and _easy to use_ solution for global state. It's not a full flux / redux style state management solution, as we know from experience that these solutions (while very useful and cool), may lead to performance issues on low-end devices.
+
+## Registering the plugin
+
+The Global App state plugin is provided in the core Blits package, but as it's an _optional_ plugin it first needs to be registered.
+
+The plugin can be imported from Blits and registered in the App's `index.js`, as demonstrated in the example below.
+
+Make sure to place the `Blits.Plugin()` method _before_ calling the `Blits.Launch()` method.
+
+```js
+// index.js
+
+import Blits from '@lightningjs/blits'
+// import the app state plugin
+import { appState } from '@lightningjs/blits/plugins'
+
+import App from './App.js'
+
+// Use the Blits App State plugin
+Blits.Plugin(appState, {
+  loggedIn: false,
+  user: {
+    id: null,
+    name: '',
+    lastname: ''
+  },
+  languages: ['en', 'nl', 'pt', 'es'],
+})
+
+
+Blits.Launch(App, 'app', {
+  // launch settings
+})
+```
+
+### State object
+
+When registering the Global App State plugin, you pass it a state object as the second argument. This is a plain object literal that will be converted into a _reactive_ object, and is used to keep track of the global state variables.
+
+The newly created Global App state works exactly the same as an internal Component state. You can read values and you can directly change values. And when you do change a value, it automatically triggers reactive updates. Either via reactive attributes in the template, or in the form of watchers / computed values in the Component logic.
+
+### Using global app state in a Component
+
+Any variable in the Global App state can be used directly in the template, much like a local Component state. Changing values in the global app state also works exactly the same as updating the internal component state.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
+    </Element>
+  `,
+  input: {
+    enter() {
+      this.$appState.user.name = 'John'
+      this.$appState.loggedIn = true
+    }
+  },
+})
+```
+
+Note that in the template definition, 2 consecutive dollars signs are used (`$$appState`). The first `$`-sign is used
+to refer to the Component scope, as with any other state variable or computed property referenced in the template.
+
+The second `$`-sign is needed, since the appState plugin itself is prefixed with a dollar sign, to prevent accidental naming collisions.
+
+In order to read or update variables on the global app state inside the component logic, you can access the entire state via `this.$appState`.
+
+### Watching global state
+
+Similar to component state, you can watch for changes in the global state as well. You can refer to global state variables using _dot-notation_ in the watcher function name, and _prefixing_ it with `$appState`. This means that you need to define your watcher as a `String`, matching one of the examples below, depending on your style preference.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
+    </Element>
+  `,
+  watch: {
+    '$appState.fooBar'(v, old) {
+      console.log(`$appState.fooBar changed from ${old} to ${v}`)
+    },
+    '$appState.my.nested.data': function(v, old) {
+      console.log(`My nested App state data changed!`)
+    }
+  },
+})
+```