@lightningjs/blits 1.30.1 → 1.30.2

package/docs/essentials/template_syntax.md

@@ -1,83 +1,83 @@
-# 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>
-  `
-})
-```
+# 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 +1,58 @@
-# 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`.
-
+# 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 +1,45 @@
-# 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.
+# 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 +1,20 @@
-# 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 🙂
-
+# 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 +1,47 @@
-<!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>
+<!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>