@lightningjs/blits 0.8.1 → 0.9.1

package/docs/{displaying_images.md → essentials/displaying_images.md}

@@ -2,12 +2,11 @@
 
 ## 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 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 (e.g., `public/assets/background.jpg` or `public/images/logo.png`) and refer to them with a _relative_ path (omitting the `public` folder as root).
+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`).
 
@@ -18,13 +17,15 @@ Remote images are also supported and can be linked directly (e.g., `http://mycdn
 
 ### Sizing and Scaling
 
-Make sure to give your Element a width (`w` ) and a height (`h`) attribute. Blits will scale the image to fit these exact dimensions.
+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.
+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 the a solid white background, which corresponds with the actual colors of the image.
+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 the a solid white background, with the result that the actual colors of the image will be shown.
 
 ```xml
 <Element
@@ -47,7 +48,7 @@ You can use this, for example, to only make something visible once an image is f
 
 > Note how events are prefixed with a `@` sign.
 
-Considering the template above, in the `methods` key of your Component configuration object, you would then do something like:
+Considering the template above you would do something like the following in the `methods` key of your Component configuration object:
 
 ```js
 {
@@ -66,4 +67,3 @@ Considering the template above, in the `methods` key of your Component configura
 ```
 
 The `loaded` event receives the images dimensions as it's argument and the `error` event receives an error message explaining the failure.
-

package/docs/essentials/displaying_text.md

@@ -0,0 +1,77 @@
+# Blits - Lightning 3 App Development Framework
+
+## Displaying Text
+
+Besides displaying images, it is also very common to have _texts_ in an App.
+
+Blits comes with a built-in `<Text>`-tag for displaying and styling texts in a simple and intuitive way.
+
+```xml
+<Text
+  content="Hello world"
+  font="ComicSans"
+  size="$fontSize"
+  :color="$changingColor"
+/>
+
+```
+You can use the Text-tag anywhere in your template, without the need to explicitly import and register it in your Component.
+
+### Available attributes on the Text tag
+
+The Text-tag accepts the following of attributes:
+
+- `content` - the text to be displayed. Can be a hardcoded text, a dynamic value or a reactive value
+- `font` - the font family, defaults to `lato`, or the default font specified in the launch settings
+- `size`  - the font size, defaults to `32`
+- `color` - the color to display for the text, defaults to `white` and can be any of the supported Blits color formats (html, hexedecimal or rgb(a))
+- `letterspacing` - letterspacing in pixels, defaults to `0`
+- `align` - the alignment of the text, can be `left`, `right` or `center`, defaults to `left`. Centering text and aligning text to the right requires the `wordwrap` attribute to be set as well.
+- `wordwrap` - the max length of a line of text in pixels, words surpassing this length will be broken and wrapped onto the next line. This atribute is required when aligning center or right
+- `maxlines` - maximum number of lines that will be displayed
+- `maxheight` - maximum height of a text block, lines that don't fit within this height will not be displayed
+- `lineheight` - the spacing between lines in pixels
+- `contain` - the strategy for containing text within the bounds, can be `none` (default), `width` or `both`. In most cases the value of this attribute will automatically be set by Blits based on the other specified attribites
+- `textoverflow` - the suffix to be added when text is cropped due to bounds limits, defaults to `...`
+
+
+### SDF and Canvas2d
+
+Compared to Lightning 2, texts have improved a lot in Lightning 3, thanks to the SDF (Signed Distance Field) Text renderer.
+
+With the SDF text renderer, texts appear a lot _sharper_ on screen. The SDF technique also allows for better scaling of texts, without them becoming blurry - a well known painpoint in Lightning 2 Apps.
+
+ In general it's recommended to use the SDF text renderer, but Lightning 3 still has a Canvas2d text renderer as a backup, and you can use both text renderers within the same App.
+
+### Using custom fonts
+
+The `font`-attribute on the `<Text>`-tag is used define which font family should be used for a certain piece of text.
+
+When you create a new Blits app using the available [getting started boilerplate](../getting_started/getting_started.md) you'll be able to use the `lato` (Lato regular) and `raleway` (Raleway ExtraBold) fonts out of the box.
+
+But of course you can also use any custom font that you want, to give your App the unique look and feel that fits with the design.
+
+Adding is custom font to a Blits App is quite straightforward. First you'll need to place a `.ttf` version of your font in the `public` folder (i.e. `public/fonts/comic-sans.ttf`).
+
+Then you'll need to register the custom font in the Launch settings of your app (in `src/index.js`). The `fonts`-key in the settings is an `Array` that specifies all available fonts in your App.
+
+Just add a new font object with the necesarry details:
+
+```js
+  fonts: [
+    // ...
+    {
+      family: 'ComicSans', // the font name used in your App
+      type: 'msdf', // type of text renderer to use (msdf or web)
+      file: 'fonts/Comic-Sans.ttf', // location of the ttf file
+    },
+    // ..
+  ],
+  ```
+
+From this moment on you'll be able to use the font `ComicSans` anywhere in your App:
+
+```xml
+<Text font="ComicSans" content="I'm Comic Sans font!" />
+```
+

package/docs/{element_attributes.md → essentials/element_attributes.md}

@@ -1,10 +1,10 @@
 # Blits - Lightning 3 App Development Framework
 
-## Styling and positioning Elements
+## Supported Element attributes
 
-The core building block of a Blits template is the Element tag. The Element tag corresponds directly to a node in the Lightning 3 Renderer. You can style and position Elements via _attributes_, much like you would do in HTML.
+The core building block of a Blits template is the `<Element>`-tag. The Element tag corresponds directly to a node in the Lightning 3 Renderer. You can style and position Elements via _attributes_, much like you would do in plain HTML.
 
-Blits Elements have a specific set of attributes that can be set, loosely modeled after the properties of a Lightning 3 renderer node. In certain cases Blits provides more developer friendly names or accepts a wider range of values, and transparently takes care of the translation into L3 renderer instructions.
+Blits Elements have a specific set of attributes that can be used. The available attributes are loosely modeled after the properties of a Lightning 3 renderer node. In certain cases Blits provides more developer friendly names or accepts a wider range of values, and transparently takes care of the translation into L3 renderer instructions.
 
 ### Positioning and Dimensions
 
@@ -16,7 +16,7 @@ In order to position and set the dimensions of an Element, the following attribu
   - `w` - the width of the element in pixels (optionally `width` can be used as an alias)
   - `h` - the height of the element in pixels (optionally `height` can be used as an alias)
 
-All positioning and dimension related attributes, when not specified, default to `0`.
+All positioning and dimension related attributes, when not specified, will default to `0`.
 
 ```xml
 <Element x="100" y="100" w="800" h="400">
@@ -34,16 +34,17 @@ Besides using values in pixels (i.e. `w="100" h="300"`), you can also specify _p
   <Element w="42%" h="30%" y="5%" x="1%" color="#075985" />
 </Element>
 ```
-The percentage specified in `w` and `x` will be calculated as the percentage of the _width_ (`w`) of the parent element.
-And the percentage specified in `h` and `y` will use the _height_ (`h`) of the parent element as the base of the percentage calculation.
+
+The percentage value specified for `w` and `x` will be calculated as the percentage of the _width_ (`w`) of the parent element.
+And the percentage specified for `h` and `y` will use the _height_ (`h`) of the parent element as the base of the percentage calculation.
 
 ### Colors
 
 By default Elements have a transparent background color. The `color` attribute can be used to give an Element a color.
 
-For those familiar with Lightning 2: colors have gotten a lot easier with Blits! Under the hood the Lightning 3 renderer still uses the somewhat unfamiliar, but efficient `0xffc0ffee` syntax. In Blits you can specify colors as you are used to in HTML and CSS.
+If you are familiar with Lightning 2: colors have gotten a lot easier with Blits. Under the hood the Lightning 3 renderer still uses the somewhat unfamiliar (but efficient) `0xffc0ffee` syntax. In Blits you can specify colors as you are used to in HTML and CSS.
 
-Blits accepts the following color formats and makes sure that they are mapped in a way the Lightning 3 renderer can understand.
+Blits accepts the following color formats and makes sure that they are converted in a way the Lightning 3 renderer can understand.
 
 - hexadecimal (i.e. `#ff4433`)
 - hexadecimal with an alpha channel (i.e `#55553380`)
@@ -52,7 +53,7 @@ Blits accepts the following color formats and makes sure that they are mapped in
 - rgba (i.e `rgba(40, 30, 180, 0.5)`)
 - html color names (i.e. `red`, `blue`, `skyblue`, `tomato`)
 
-HSL and HSLA formats are planned to be added in the future.
+_HSL and HSLA formats are planned to be added in the future._
 
 ```xml
 <Element w="200" h="200" color="#ff4433" />
@@ -69,7 +70,9 @@ HSL and HSLA formats are planned to be added in the future.
 
 The color attribute can also be used to specify basic linear gradients.
 
-A linear gradient can be defined by specifying an _object literal_ as the `color` attribute instead of a single color. The object can consist of a mix of `top`, `bottom`, `left`, `right` keys, with the color to use for that side as a value. If a specific side isn't specified, it defaults to `transparent`. Again you can use "normal" notation for the colors (like hexadecimal or rgba) and you are free to mix and match formats.
+A linear gradient can be defined by specifying an _object literal_ as the `color` attribute instead of a single color. The object can consist of a mix of `top`, `bottom`, `left`, `right` keys, with the color to use for that side as a value. If a specific side isn't specified, it defaults to `transparent`.
+
+Again, you can use "normal" notation for the colors (like hexadecimal or rgba) and you are free to mix and match formats.
 
 ```xml
 <Element w="200" h="200" color="{top: 'red', bottom: 'blue'}" />
@@ -82,7 +85,7 @@ A linear gradient can be defined by specifying an _object literal_ as the `color
 
 The opacity of an Element, can be controlled by setting the `alpha` attribute. This attribute accepts a value between `0` (fully transparent) and `1` (completely visible).
 
-The value of alpha is also being applied recursively to the children of the Element that has its alpha set. If you just want the background color of an Element to be semi-transparent, you should set the alpha channel in the color instead of applying the alpha attribute.
+The value of alpha is also being applied recursively to the children of the Element that has its alpha set. If you just want the background color of an Element to be semi-transparent, you should set the alpha channel in the `color` instead of applying the `alpha` attribute.
 
 ```xml
   <Element w="200" h="200" color="blue" alpha="0.8">
@@ -106,7 +109,7 @@ For scaling an Element the `scale` attribute is used.
 
 This attribute either accepts a single numeric value for scaling evenly accross width and height. Or an _object literal_, if you want to apply a different scaling for the `x` and the `y` axis.
 
-The value should start at `0` and the default value is `1`, which means no scaling.
+The value should be higher than `0` and the default value is `1`, which means no scaling.
 
 Any value below `1` will scale _down_ the element and values greater than `1` will scale the element _up_.
 
@@ -152,3 +155,5 @@ In the case where the `x` and `y` values are the same, you can also just supply
 <Element w="200" h="200" x="800" y="400" pivot="{y: 1}" scale="3" />
 <Element w="200" h="200" x="800" y="700" pivot="0.9" rotation="42" />
 ```
+
+<!-- ### Clipping -->

package/docs/essentials/template_syntax.md

@@ -0,0 +1,85 @@
+# Blits - Lightning 3 App Development Framework
+
+## 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 a template 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 orgnize your codebase with custom components, abstracting a complex template into smaller, resuable pieces.
+
+When you've abstrated 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

@@ -0,0 +1,61 @@
+# Blits - Lightning 3 App Development Framework
+
+## 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 if often the case with Lightning apps).
+
+### index.html
+
+You will also find an `index.html` in 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 the 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 by an `id` of an html element in `index.html`, or you can pass a reference the 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 you App can be built out using components. You are free to organize your components as you wish, but we recommend
+to use a separate file for each component, and place 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 thing 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 accross 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

@@ -0,0 +1,47 @@
+# Blits - Lightning 3 App Development Framework
+
+## 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
+npx @lightningjs/blits@latest
+```
+
+ 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/{introduction.md → getting_started/intro.md}

@@ -16,4 +16,5 @@ 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 teams is based in the Netherlands). It means _flashy_ and it's often used to 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
+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/sidebar.json

@@ -3,61 +3,105 @@
     "text": "Getting Started",
     "items": [
       {
-        "text": "Introduction",
-        "link": "/introduction"
+        "text": "Intro",
+        "link": "/getting_started/intro"
       },
       {
-        "text": "Setup",
-        "link": "/getting_started"
+        "text": "Getting started",
+        "link": "/getting_started/getting_started"
+      },
+      {
+        "text": "File structure",
+        "link": "/getting_started/file_structure"
       }
     ]
   },
   {
-    "text": "Basics",
+    "text": "Essentials",
     "items": [
       {
-        "text": "Components",
-        "link": "/components"
+        "text": "Application root",
+        "link": "/essentials/application_root"
       },
       {
-        "text": "Template Syntax",
-        "link": "/template_syntax"
+        "text": "Component basics",
+        "link": "/essentials/components"
       },
       {
-        "text": "Component State",
-        "link": "/component_state"
+        "text": "Template syntax",
+        "link": "/essentials/template_syntax"
       },
       {
-        "text": "Hooks",
-        "link": "/lifecycle_events"
+        "text": "Supported element attributes",
+        "link": "/essentials/element_attributes"
       },
       {
-        "text": "Props",
-        "link": "/props"
+        "text": "Displaying images",
+        "link": "/essentials/displaying_images"
       },
       {
-        "text": "User Input",
-        "link": "/user_input"
+        "text": "Displaying text",
+        "link": "/essentials/displaying_text"
+      }
+    ]
+  },
+  {
+    "text": "Components",
+    "items": [
+      {
+        "text": "State",
+        "link": "/components/component_state"
+      },
+      {
+        "text": "Props",
+        "link": "/components/props"
       },
       {
-        "text": "Computed Props",
-        "link": "/computed_properties"
+        "text": "Computed properties",
+        "link": "/components/computed_properties"
       },
       {
         "text": "Watchers",
-        "link": "/watchers"
+        "link": "/components/watchers"
       },
       {
-        "text": "Styling",
-        "link": "/element_attributes"
+        "text": "Hooking into lifecycle events",
+        "link": "/components/lifecycle_events"
       },
       {
-        "text": "Images",
-        "link": "/displaying_images"
+        "text": "Handling User input",
+        "link": "/components/user_input"
       },
       {
-        "text": "Text-to-Speech",
-        "link": "/text-to-speech-announcer"
+        "text": "Methods",
+        "link": "/components/methods"
+      }
+    ]
+  },
+  {
+    "text": "Transitions and Animations",
+    "items": [
+      {
+        "text": "Transitions",
+        "link": "/transitions_animations/transitions"
+      }
+    ]
+  },
+  {
+    "text": "Built-in components",
+    "items": [
+      {
+        "text": "Directives",
+        "link": "/built-in/directives"
+      }
+    ]
+  },
+  {
+    "text": "Plugins",
+    "items": [
+      {
+        "text": "Text-to-Speech / Announcer",
+        "link": "/plugins/text-to-speech-announcer"
       }
     ]
   }