@lightningjs/blits 1.30.2 → 1.31.1

package/docs/getting_started/file_structure.md

@@ -1,58 +0,0 @@
-# File structure
-
-Once you have created a new Blits App using the boilerplate described in the [Getting started](getting_started.md), you should have a project with all the basics you need.
-
-Let's review the basic file structure, and take a closer look at the important ones.
-
-## package.json
-
-In the root of your newly created app, you will obviously find a `package.json` with all the necessary (dev) dependencies.
-
-In order to build a Blits based Lightning 3 app, all you need is `@lightningjs/blits` as a dependency. Blits will take care of hooking up the Lightning 3 renderer for you behind the scenes.
-
-Feel free to install and import any custom library that your App may need. But always be mindful of the size and impact an external dependency may have - especially when developing for low powered devices (as is often the case with Lightning apps).
-
-## index.html
-
-You will also find an `index.html` at the root of your project. This is where the browser will be pointed to, in order to launch your Blits App.
-
-If you inspect the source you will see some minimal HTML. The essential parts of the HTML are the `<div>` where the canvas will be injected into, and the `<script>`-tag that points to the `index.js` of the App.
-
-## public
-
-There is also a `public` folder in your project. This folder is used for storing public assets, such as App images and fonts.
-
-During development, your assets are loaded directly from this folder. And if you run a production build, the entire `public` folder is copied over to the distributable version.
-
-## src
-
-The `src`-folder is where all your custom App code lives.
-
-### index.js
-
-`src/index.js` is the entry point of your App. This file imports the Blits `Launch`-method which initializes the App.
-
-The `Blits.Launch()`-method accepts 3 parameters:
-
-1) `app` - the root application component
-2) `target` - the HTML target to append the canvas to. This can either be an `id` of an HTML element in `index.html`, or you can pass a reference to HTML element itself
-3) `settings` - an `object` with settings
-
-### App.js
-
-`src/App.js` is the default file where the root application component lives. It's expected to export a `Blits.Application()`-instance, which is the base component of your App.
-
-## components and pages folder
-
-The rest of your App can be built out using components. You are free to organize your components as you wish, but we recommend using a separate file for each component and placing them in the `src/components`-folder.
-
-The convention is to start the component file name with a capital letter, matching the name of the component (e.g. `src/components/Loader.js` or `src/components/MenuItem.js`).
-
-Feel free to further organize and possibly nest your Component files to your own preferences.
-
-Pages in your App are technically just Blits components as well. But to keep things clear, we often place them in a separate `pages`-folder alongside the `components`-folder (e.g. `src/pages/Home.js` and `src/pages/Details.js`)
-
-### Custom code
-
-If your App needs libraries for specific (business) logic that can be shared across components (such as API calls) you can place them anywhere in your `src` folder. For example in a folder named `src/lib` or `src/api`.
-

package/docs/getting_started/getting_started.md

@@ -1,45 +0,0 @@
-# Getting Started
-
-To get started with Blits, follow these simple steps to set up your development environment and create your first Lightning 3 App.
-
-## Installation
-
-1. Open your terminal or command prompt.
-
-2. Run the following command to start a new Blits Lightning 3 App project:
-
-```bash
-npm create @lightningjs/app
-```
-
- You will be guided through a short series of questions to generate a new project with all the boilerplate code you need to start building your own Lightning 3 App.
-
-3. Navigate to the newly created project directory and install the project dependencies:
-
-```bash
-cd my_blits_app
-npm install
-```
-
-## Running Your App
-
-4. After installing the dependencies, you can start your development server by running:
-
-```bash
-npm run dev
-```
-
-This command will create an application bundle and launch a development server using Vite.
-
-Once the server is up and running, open your web browser and navigate to the URL displayed in the console. Congratulations! You now have your brand new Blits Lightning 3 App up and running.
-
-## Coding environment
-
-You can use any code editor of your preference to further develop your Blits App.
-
-We recommend using VS code, since we have a dedicated [VS code extension for Blits](https://marketplace.visualstudio.com/items?itemName=LightningJS.lightning-blits) that provides better syntax highlighting, code completion, error
-checking, and other features to make working with Blits easier.
-
-## Next steps
-
-You are now ready to dive into the world of App development using Blits. In the following sections, we will explore the core concepts and guide you through building your TV applications step by step.

package/docs/getting_started/intro.md

@@ -1,20 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-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!
-
-Built from the ground up by the LightningJS team, we're offering a **Complete App framework**, full of features to speed up development, while keeping it **lightweight** with a focus on **performance**.
-
-The Blits framework uses a **readable** XML-style template syntax and comes with built-in reactivity.
-
-## Why Blits?
-
-You may be wondering where the name Blits comes from.
-
-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 team is based in the Netherlands). It means _flashy_ and it's often used 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 🙂
-

package/docs/index.html

@@ -1,47 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Blits Lightning App Development Framework</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
-  <!--link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"-->
-  <link
-    rel="stylesheet"
-    href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
-    title="docsify-darklight-theme"
-    type="text/css"
-/>
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'Blits <br />L3 App Development Framework',
-      repo: 'https://github.com/lightning-js/blits/',
-      loadSidebar: true,
-      relativePath: true,
-      auto2top: true,
-      search: {
-        maxAge: 24*60*60*1000, // one day
-        paths: 'auto',
-        placeholder: 'Type to search',
-        noData: 'No Results!',
-        depth: 6,
-      },
-      darklightTheme: {
-        defaultTheme : 'dark',
-      }
-    }
-
-  </script>
-  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
-  <script
-    src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
-    type="text/javascript">
-</script>
-  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
-</body>
-</html>

package/docs/performance/lazy-loading.md

@@ -1,161 +0,0 @@
-# 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 +0,0 @@
-# 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!`)
-    }
-  },
-})
-```

package/docs/plugins/language.md

@@ -1,172 +0,0 @@
-# Language plugin
-
-Blits comes with a built-in Language plugin, that can be used to add internationalization (i18n) to your App.
-
-The Blits Language plugin is a simple and lightweight implementation, closely modeled after the tried and tested Language plugin in the Lightning-SDK (for Lightning 2). It is designed to provide a flexible and easy way of translating texts to multiple languages, in a performant way.
-
-## Registering the plugin
-
-While the Language plugin is provided in the core Blits package, it's an _optional_ plugin that needs to be registered before you're able to use it. As such the Language plugin is _tree-shakable_, i.e. for Apps that don't have a need for translation functionality, the Language plugin will not be part of the final App bundle.
-
-The Language plugin should 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 language plugin
-import { language } from '@lightningjs/blits/plugins'
-
-import App from './App.js'
-
-// Use the Blits Language plugin and
-// optionally pass in a settings object
-Blits.Plugin(language, {
-  file: '/assets/translations.json', // file with translations
-  language: 'EN-us', // default language
-})
-
-
-Blits.Launch(App, 'app', {
-  // launch settings
-})
-```
-
-The Language plugin accepts an optional configuration object with 2 keys:
-
-- `file` - the JSON file with translations to be loaded at initialization
-- `language` - the default language to use
-
-After registration of the Language plugin, it will be available in each Blits Component as `this.$language`.
-
-## Translations file
-
-The most common way of defining a set of translations, is to use a dedicated JSON file, modeled after
-the following format:
-
-```json
-{
-    "nl-NL": {
-      "hello": "Hallo, alles goed?",
-      "bye": "Doei!",
-      "replacement": "Mijn naam is {first} {last}, ik ben {age} jaar"
-    },
-    "en-US": {
-      "hello": "Hello, how are you doing?",
-      "bye": "Goodbye!",
-      "replacement": "My name is {first} {last}, I'm {age} years old"
-    },
-    "fr-FR": {
-      "hello": "Bonjour, ça va?",
-      "bye": "Au revoir!",
-      "replacement": "Je m'appelle {first} {last}, j'ai {age} ans"
-    },
-    "de-DE": {
-      "hello": "Gutentag, wie geht's?",
-      "bye": "Tschüss!",
-      "replacement": "Mein Name ist {first} {last}, ich bin {age} Jahre alt"
-    }
-  }
-```
-
-Each top level key represents a language, which contains an object with translation key-value pairs. The language key
-doesn't require to be in a specific format, but it's recommended to use ISO-codes.
-
-When the JSON file is specified in the Plugin registration method, the language file is loaded automatically upon instantiation.
-
-In case you want to load the file with translations manually, you can use the `this.$language.load()`-method anywhere in a Component and pass in the path to the JSON file as the first argument.
-
-## Defining translations manually
-
-As an alternative to a JSON file with translations, you can also define translations directly via an object, using the `translations()`-method.
-
-The `this.$language.translations()`-methods accepts a translations object as it's first argument, following the same format as the JSON file. The method is typically used in an `init` or `ready` hook
-
-```js
-Blits.Component('MyComponent', {
-  // ...
-  hooks: {
-    init() {
-      this.$language.translations({
-        english: {
-          hello: "Hello",
-          world: "World"
-        },
-        italian: {
-          hello: "Ciao",
-          world: "Mondo"
-        }
-      })
-    }
-  },
-})
-```
-
-## Setting the language
-
-In order to set (or change) the current language, the `this.$language.set()`-method can be used, passing in the new language code (matching one of the languages defined in the translations).
-
-```js
-Blits.Component('MyComponent', {
-  // ...
-  input: {
-    enter() {
-      this.$language.set('pt-BR')
-    }
-  },
-})
-```
-
-## Getting the current language
-
-The current language can be retrieved via the `this.$language.language` property. It will return the currently set language code.
-
-## Translating
-
-The most important functionality in the Language plugin is translating. The Language plugin exposes a `translate()` method that takes as string to translate as it's first argument. It will return the translated value in the currently set language. If either the language or the string to translate can't be found, it will return the inputed string.
-
-The translate method can be used both inside the javascript business logic, but also directly in the template.
-
-```js
-Blits.Component('MyComponent', {
-  template: `
-    <Element>
-      <Text :content="$$language.translate('hello')" />
-      <Text y="100" :content="$$language.get()" />
-    </Element>
-  `,
-  hooks: {
-    ready() {
-      console.log(this.$language.translate('world'))
-    }
-  },
-})
-```
-
-Note that in the template definition 2 consecutive dollars signs are used (`$$language`). The first `$`-sign is used
-to refer to the Component scope, as with any other state variable or computed property refereced in the template.
-
-The second `$`-sign is needed, since the Language plugin itself is prefixed with a dollar sign on the Component scope as well (i.e `this.$language`).
-
-
-### Dynamic replacements
-
-The `tranlate()`-method also supports dynamic replacements. This allows you to specify variables inside your translation string, and replace them with dynamic values passed into the `translate()`-method.
-
-Replacements are marked in the translation value using _handlebars_, like so:
-
-```js
-{
-  replacements = "My name is {first} {last}, I'm {age} years old"
-}
-```
-
-Now when you call the `translate()`-method and pass in an object with dynamic values, those will be replaced
-in the final string accordingly:
-
-```js
-this.$language.translate('replacements', {name: 'John', last: 'Doe', age: 18})
-// result: My name is John Doe, I'm 18 years old
-```