@lightningjs/blits 1.30.1 → 1.31.0

package/docs/essentials/template_syntax.md

@@ -1,83 +0,0 @@
-# Template syntax
-
-Blits uses an easy-to-read _XML-style_ template syntax. The syntax is inspired by frameworks like VueJS, so if you are familiar with Vue, you will probably recognize certain concepts.
-
-The `template` key in the _Component configuration object_ is used to specify a string with this XML-like template structure. Templates can often span multiple lines. In those cases, it's advisable to use `template literals` (enclosed by backticks).
-
-Similar to HTML, you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported in Blits templates.
-
-The default tag that can be used in templates is the `<Element>` tag. The Element tag corresponds to a node in the Lightning 3 renderer.
-
-For each element, there is a set of predefined render properties, such as `x`, `y`, `w`, `color` that define how the element looks and where it is positioned. Detailed information on all the attributes supported by the `<Element>` tag can be found [here](./element_attributes.md).
-
-Now let's consider the following template example:
-
-```xml
-<Element x="20" y="20">
-  <Element w="100" h="100" x="360" color="#0891b2" />
-  <Element w="$width" h="$height" color="$color" />
-  <Element :w="$changingWidth" :h="Math.floor($height / 5)" :color="$highlight" />
-</Element>
-```
-
-## Hardcoded arguments
-
-In the template above, you'll observe certain arguments with hardcoded values (i.e. `w="100"` and `color="#0891b2"`).
-You can use hardcoded arguments to configure the parts of your template that you know will never change.
-
-## Dynamic arguments
-
-Additionally, some arguments contain a value prefixed with a dollar sign (`$`). These are so called _dynamic_ arguments.
-
-The `$`-sign used in a template refers to a (state) variable on the Component. And when the template renders, it automatically populates
-these arguments with dynamic values based on the initial state of your Component.
-
-It's important to realize that dynamic arguments are only set _once_. Changing a value used in a dynamic argument, won't be reflected
-on screen. For that you will need to use _reactive_ arguments.
-
-## Reactive arguments
-
-If you look at the template example above you'll notice that certain arguments are prefixed with a colon sign (`:`). Prefixing an argument
-with a colon makes it not only dynamic but also _reactive_.
-
-Reactive arguments are set with the initial state value when your component first renders, exactly as a dynamic argument does.
-
-The difference is that a _re-render_ of (a portion of) the template will be triggered whenever the referenced value in your Component's internal state changes.
-
-This concept of _reactive data binding_ eliminates the need for manual template patching and allows for a declarative way of programming.
-
-Reactive arguments also support _interpolation_. This enables the use of simple JavaScript instructions, such as ternary conditions or basic String and Math manipulations, right inside your template arguments.
-
-For more complex logic, it's recommended to abstract this into a [Component method](../components/methods.md) or a [Computed property](../components/computed_properties.md).
-
-# Abstracting template portions to custom components
-
-As your template grows in complexity, you may want to organize your codebase with custom components, abstracting a complex template into smaller, reusable pieces.
-
-When you've abstracted a portion of a template into a separate component, a _Menu_ component for example, you'll first need to `import` the file that contains the Menu component.
-
-Next, you have to _register_ the imported custom component. The `components`-key in the _configuration object_ is used for this.
-
-The `components` key is an _object literal_, where the value is the reference to the custom Blits component and the key will correspond with the _tag_ that can be used in the template to insert the component.
-
-Once this is done, the tag (`<Menu>` for example) is available for use in your component's template. You can use the component tag as many times as you want. For each tag, a new Component instance will be created.
-
-The example below shows how to use a custom `Menu` and `Button` (aliased to `MyButton`) component inside a template.
-
-```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/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!`)
-    }
-  },
-})
-```