@lightningjs/blits 0.9.6 → 0.9.8

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v0.9.8
+
+_25 apr 2024_
+
+- Fixed issue with removing children during navigation with the router
+- Added support for overflow (as an inversed alias of clipping)
+- Upgraded to latest version of renderer (0.8.3)
+- Introduced `renderMode` setting (`webgl` or `canvas`)
+
+## v0.9.7
+
+_15 apr 2024_
+
+- Added support for direct assignment of an Array element and triggering reactivity
+- Added support for .env in boilerplate
+- Fixed issue with Blits component being wrapped in a Proxy when assigned to a state variable
+- Fixed built-in `hasFocus`-state to also work for components that don't have state in their config object
+
 ## v0.9.6
 
 _4 apr 2024_
@@ -29,7 +47,7 @@ _25 mar 2024_
 
 - Added support for mount / pivot on Text elements and Sprites.
 
-# v0.9.2
+## v0.9.2
 
 _21 mar 2024_
 

package/boilerplate/common/eslint/.eslintrc.cjs

@@ -32,7 +32,7 @@ module.exports = {
   },
   parserOptions: {
     parser: 'babel-eslint',
-    ecmaVersion: 2018,
+    ecmaVersion: 2020,
     sourceType: 'module',
   },
 }

package/boilerplate/common/git/gitignore

@@ -1,5 +1,8 @@
 .DS_Store
+.env
+.env.*
+!.env.example
+
 node_modules
 build
 dist
-env

package/boilerplate/js/default/.env.example

@@ -0,0 +1,4 @@
+# all environment variables need to prefixed with VITE_*
+# to read, use import.meta.env.VITE_FOO
+
+# VITE_FOO=bar

package/boilerplate/js/default/src/pages/Home.js

@@ -2,7 +2,7 @@ import Blits from '@lightningjs/blits'
 
 import Loader from '../components/Loader.js'
 
-export default Blits.Component('Loading', {
+export default Blits.Component('Home', {
   components: {
     Loader,
   },

package/boilerplate/js/default/vite.config.js

@@ -1,3 +1,5 @@
+/// <reference types="vite/client" />
+
 import { defineConfig } from 'vite'
 import blitsVitePlugins from '@lightningjs/blits/vite'
 

package/docs/_sidebar.md

@@ -21,5 +21,6 @@
   - [Transitions](/transitions_animations/transitions.md)
 - Built-in components
   - [Directives](/built-in/directives.md)
+  - [For loop](/built-in/for-loop.md)
 - Plugins
   - [Text-to-Speech / Announcer](/plugins/text-to-speech-announcer.md)

package/docs/built-in/directives.md

@@ -2,13 +2,13 @@
 
 ## Directives
 
-Blits comes with a few built-in attributes that tap into specific behaviour provided by the framework - also kn ows as _directives_. Most of them can be used in the template on both Elements and Components.
+Blits comes with a few built-in attributes that tap into specific behaviour provided by the framework - also known as _directives_. Most of them can be used in the template on both Elements and Components.
 
 ### Show-directive
 
-The `show`-attribute allows you to conditionally show and hide Components and Elements.
+The `show` attribute allows you to conditionally show and hide Components and Elements.
 
-When passed a _truthy_ value, such as `true` or `1`, the element will be made visible. And when passed a _falsy_ value (`false` or `0`) it will not be visible.
+When passed a _truthy_ value, such as `true` or `1`, the element will be made visible. And when passed a _falsey_ value (`false` or `0`) it will not be visible.
 
 ```xml
 <Element>
@@ -39,6 +39,14 @@ export default Blits('DynamicComponents', {
 
 At the moment it's not possible to use the `is`-attribute as a _reactive_ attribute and have a component change type after instantiation.
 
+### Ref-attribute
+
+The declarative coding style that is promoted in Blits components, should generally remove the need to directly interact with individual Elements or Components in your template. However, in some cases you may need to reference them directly. For example, in order to delegate the focus.
+
+For this use case, you can specify a `ref`-attribute on Elements (or Components). And by using the helper function `this.select()`,  which is vailable on every Blits component, you can gain access to the child Element or Component inside your business logic.
+
+The `select()`-function accepts the `ref`-value that you are looking for as a single argument, and returns the Element or Component if found.
+
 <!-- ### If-directive
 
 Todo -->

package/docs/built-in/for-loop.md

@@ -0,0 +1,172 @@
+# Blits - Lightning 3 App Development Framework
+
+## For loop
+
+The for loop is technically also a [directive](../directives.md), but such an important one that it deserves it's own section.
+
+The for loop directive can be used when you want to repeat multiple instances of an Element or a Component, without having to specify them hardcoded one by one in your template.
+
+The for loop take an `Array` of data, loops over it and for each Array-item an Element or Component is created. The `Array` can be a fixed one, but it' can also dynamically be filled or modified and have it's changes reflect in the rendered result.
+
+> Important: the for loop is a powerful and often used directive. Within Blits it's optimized to be as performant as possible. But if used incorrectly, it can be the cause of slow performance. So please read carefully through this entire section.
+
+
+### Basic syntax
+
+The for-loop directive should be added as an attribute on the Element or Component that you want to repeat for each item in your Array. In the template syntax a `for ... in` construct is used. This ultimately transpiles down to a classic, optimized for loop.
+
+```js
+export default Blits('ForLoop', {
+  template: `
+    <Element>
+      <Element :for="item in $items" w="100" h="100" color="lime" />
+    </Element>
+  `,
+  state() {
+    return {
+      items: ['Item 1', 'Item 2', 'Item 3']
+    }
+  },
+})
+```
+
+The example above will generate 3 _lime green_ elements, based on the array of `items` in the Component state. They will appear on top of each other though, since they have no `x` and `y` positioning (which default to 0).
+
+
+### Using the index
+
+In order to fix the example above and make all 3 elements visible, we can use the `index` of the Array, to position each item correctly.
+
+All we need to do is declare the `index` in the `for`-directive and subsequently use it in the the `x`-attribute, with a simple calculation.
+
+You may choose any name for the `index` variable (like `i` or `forIndex`). This may be useful when you already have the `index`-key specified as a `state` or `prop` variable on your component, causing a conflict.
+
+```js
+export default Blits('ForLoop', {
+  template: `
+    <Element>
+      <Element :for="(item, index) in $items" w="100" h="100" color="lime" :x="$index * 150" />
+    </Element>
+  `,
+  state() {
+    return {
+      items: ['Item 1', 'Item 2', 'Item 3']
+    }
+  },
+})
+```
+
+You will now see that each Element is positioned next to each other, with a 50px space in between.
+
+
+### Using variables inside a for loop
+
+When iterating over an Array in the for loop, you can reference the current Array item under the name specified in the for-in construct, prefixed with a `$`-sign. Besides this scoped Array item context, you _also_ have access to any `prop`, `state` or `computed` variable as you loop over an Array.
+
+Consider the example below, that loops over an array of _Objects_, and _also_ references the `alpha` state variable.
+
+```js
+export default Blits('ForLoop', {
+  template: `
+    <Element>
+      <Element
+        :for="(item, index) in $items"
+        w="100"
+        h="100"
+        :color="$item.color"
+        :x="$index * 150"
+        alpha="$alpha"
+      />
+    </Element>
+  `,
+  state() {
+    return {
+      alpha: 0.5,
+      items: [{
+        id: 1,
+        color: 'green'
+      }, {
+        id: 2,
+        color: 'blue'
+      }, {
+        id: 3,
+        color: 'yellow'
+      }]
+    }
+  },
+})
+```
+
+This will generate 3 squares aligned next to each other, each with a differrent color and they will use the _alpha_ specific in the Component state.
+
+### The importance of using the key attribute
+
+The examples above have demonstrated the basic usage of the for-loop. But they are all missing one _very important_ ingredient to make sure that for-loops that are subject to change, continue to perform well. Meet the `key`-attribute.
+
+For perfomance reasons, it is essential to be able track the _identity_ of an Element or Component, whenever changes are made to the Array in the for loop.
+
+Think of _identity_ as the field that makes an item in the Array unique, such as an `id` or a `hash`. It's basically the thing that allows you to distinguish between the poster of _The Matrix_ and the poster of _Frozen 2_, for example.
+
+Providing this information, allows the for-loop to decide whether it should _update_ an existing Component or Element instance. Or whether we're dealing with a new Array item, and a new instance should be _created_.
+
+Correctly using the `key`-attribute enables Blits to _reuse_ existing instances whenever possible - which obviously is good for performance.
+
+It's important that the `key`-attribute is _unique_ for each Array item. Also beware that we can't rely on the `index` parameter provided in for loop, because that only indentifies the position in the Array, and not the actual item itself.
+
+
+```js
+export default Blits('ForLoop', {
+  template: `
+    <Element>
+      <Element
+        :for="(item, index) in $items"
+        w="100"
+        h="100"
+        :color="$item.color"
+        :x="$index * 150"
+        alpha="$alpha"
+        key="$item.id"
+      />
+      <!-- ^^ id is the unique field that identifies each array item -->
+    </Element>
+  `,
+  state() {
+    return {
+      alpha: 0.5,
+      items: [{
+        id: 1,
+        color: 'green'
+      }, {
+        id: 2,
+        color: 'blue'
+      }, {
+        id: 3,
+        color: 'yellow'
+      }]
+    }
+  },
+  hooks: {
+    ready() {
+      let count = 3
+      this.$setInterval(() => {
+        this.items.push({id: count++, color: randomColor()})
+      }, 2000)
+    }
+  }
+})
+```
+
+In the example above we have added the `key`-attribute in the template. Now whenever we push a new item to the `items`-array, the for-loop will reuse the Elements previously created and only instantiate a new Element for the newly added item.
+
+If we would ommit the `key`-attribute, then whenever we push a new item to the Array, the for-loop would dispose all the old Elements and create new instances for _each_ item in the array.
+
+### Referencing elements in the for loop
+
+When you specify a `for`-attribute on an Element or a Component, it will effectively create multiple Elements / Components depending
+on the length of the Array.
+
+Generally it's not recommended to access and interact directly with Elements in a template, and that also goes for items in a For loop. But in some cases you may need to, for example to delegate focus to a specific item in the For loop.
+
+The `ref`-attribute can be used in combination with the `for`-attribute as well.
+
+Setting the _ref_ in a for loop context, can be done by either passing a string (i.e. `myitem`) and as Elements get generated in the for loop, the `index` value will be appended to it (i.e. `myitem0`, `myitem1`, etc.). Alternatively you can make the attribute interpolated and define the value for each item yourself (i.e. `:ref="'item' + $item.id"`).

package/docs/components/component_state.md

@@ -47,8 +47,7 @@ For nested objects, you can use _dot notation_ (e.g., `$style.dimensions.w`).
 In your component's code, you can reference state variables directly within the `this`-scope. For instance, a state variable named `color` can be accessed (and modified) by referencing `this.color`.
 
 It's important to note that unlike in the template, you should _not_ use the dollar sign when accessing state variables within the component's code.
-
-Also remember that there is no need to explicitely reference the `state`-key. Blits automatically maps all state variables directly on the `this`-scope, for easy access.
+Also, remember that there is no need to explicitly reference the `state`-key. Blits automatically maps all state variables directly on the `this`-scope, for easy access.
 
 The example below gives a full example of defining and using a component's state:
 

package/docs/components/computed_properties.md

@@ -4,9 +4,8 @@
 
 So far we've learned how to utilize a Component's [internal state](./component_state.md) and [props](./props.md) passed by a parent into a child component.
 
-We've also seen how we can perform simple operations like `Math.max()` or `str.toUpperCase()` directly within an argument of a template on the Component's internal state or passed props .
-
-However as these operations become more complex it's more clear and more maintainable to abstract these operations into what we call _computed properties_.
+We've also seen how we can perform simple operations like `Math.max()` or `str.toUpperCase()` directly within an argument of a template on the Component's internal state or passed props.
+However, as these operations become more complex it's more clear and more maintainable to abstract these operations into what we call _computed properties_.
 
 Computed properties are a powerful tool for enhancing the readability of your component code. By abstracting complex or frequently used calculations from your template into computed properties, you can make your code more concise and easier to understand.
 
@@ -17,7 +16,7 @@ Within the `computed`-key of the Component configuration object, you can specify
 
 A computed property function should always _return_ a value.
 
-In your template, you can reference these computed properties exactly the same as you would with _state_ variable and _props_, by prefixing them with a dollar sign (e.g., `$offset`).
+In your template, you can reference these computed properties exactly the same as you would with _state_ variables and _props_, by prefixing them with a dollar sign (e.g., `$offset`).
 
 In the rest of your app's code, you can access these computed properties (but not modify them!) using `this.offset`. Note that similar to Component state and props, you do not need to prefix with `computed` to access the computed property.
 

package/docs/components/methods.md

@@ -2,9 +2,9 @@
 
 ## Methods
 
-Within a Blits component you have quite some freedom where to put specific logic.
+Within a Blits component, you have quite some freedom where to put specific logic.
 
-Template related logic can be either be placed directly in a _reactive / interpolated_ attribute or you can move it out to a _computed property_ if the logic is more complex.
+Template related logic can be either placed directly in a _reactive / interpolated_ attribute or you can move it out to a _computed property_ if the logic is more complex.
 
 Business logic for your App can be placed directly in a _watcher_, a _lifecycle hook_ or an _input handling_ function.
 
@@ -12,7 +12,7 @@ If you notice that you're duplicating logic in these different places, or if you
 
 You can reference your Component's methods in the template by using a `$`-sign (for example in the `@loaded`-attribute when your element has a `src` attribute).
 
-In the javascript code of a Component you can reference methods directly on the `this`-scope (i.e. `this.getData()`). Similar as with `internal` state and `props`, there is no need to prefix with `methods`, for easy access.
+In the javascript code of a Component, you can reference methods directly on the `this`-scope (i.e. `this.getData()`). Similar to `internal` state and `props`, there is no need to prefix with `methods`, for easy access.
 
 ```js
 export default Blits('Carousel', {

package/docs/components/props.md

@@ -22,7 +22,7 @@ The simplest way to define props is to just list their names within the `props`
 
 Once specified, you can refer to these props inside the template of your component using the `$` sign, similar to how you would reference variables defined within the component's [internal state](./component_state.md) (i.e. `<Element color="$color" />`).
 
-You can als access a prop inside a component's code using `this.color` (without a dollar sign!). And similar to component `state` variables,
+You can also access a prop inside a component's code using `this.color` (without a dollar sign!). And similar to component `state` variables,
 there is no need to specifically reference the `props`-key. Blits automatically maps all props directly on the `this`-scope, for easy access.
 
 Since props are used to pass information from a parent to a child, it's important not to attempt to _modify_ props inside your child component. If changes based on the prop from the parent are needed, you should probably use the prop in a so called [computed property](./computed_properties.md).

package/docs/components/user_input.md

@@ -11,7 +11,7 @@ Blits offers an intuitive and straightforward interface to handle key input in C
 
 Before diving into the specifics of key handling, it is important to understand the basic concept of _focus_.
 
-In a Blits app, there is always _one_ Component that has the focus. By default this will be the root Application component.
+In a Blits app, there is always _one_ Component that has the focus. By default, this will be the root Application component.
 
 The component that has focus, is the one that is responsible for handling the user input at that moment.
 
@@ -81,7 +81,7 @@ Blits comes with a default keycode mapping. This mapping is a sensible default t
 
 But it's possible that the keycodes and mapping of your target device are slightly or even completely different.
 
-In Blits you can easily configure the key mapping to match your needs. In the `src/index.js` file where we instaniate the App via the `Blits.Launch` function, we can add an extra key, called `keys`, to the _settings object_.
+In Blits, you can easily configure the key mapping to match your needs. In the `src/index.js` file where we instantiate the App via the `Blits.Launch` function, we can add an extra key, called `keys`, to the _settings object_.
 
 The `keys` item should be an object literal, where you map a `key` or `keyCode` (from the `KeyboardEvent`) to an event name that you can use in your Components.
 

package/docs/components/watchers.md

@@ -4,7 +4,7 @@
 
 In some cases, you may want to execute specific actions whenever the value of a state variable, a prop, or a computed property changes. These actions could involve dispatching an event or updating another state variable.
 
-You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into and endless loop.
+You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, to prevent the risk of falling into an endless loop.
 
 Instead, Blits allows you to specify **watchers** to trigger functionality when certain variables change.
 

package/docs/essentials/application_root.md

@@ -6,7 +6,7 @@ Every Blits App starts with a base Application component.
 
 Ultimately this Application is a component like any regular Blits component. But it is augmented with some extra functionality. `Blits.Application` is responsible for setting up the listeners for keyhandling for example.
 
-You can only have 1 Application component per App. By default this file is named `App.js` and it is placed in the root of the `src`-folder.
+You can only have 1 Application component per App. By default, this file is named `App.js` and it is placed in the root of the `src`-folder.
 
 `src/App.js` will look something like this:
 

package/docs/essentials/components.md

@@ -20,11 +20,11 @@ Let's see how to create a new component and explore the basic anatomy of a compo
 
 A new component is created using the `Blits.Component()` function that is exported from the `@lightningjs/blits` package. This function accepts two arguments:
 
-- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader` or `SidebarMenuItem`.
+- The first argument is the _name_ of the component. This name will be used in debug log messages, so make sure to choose a unique and descriptive name for your component, such as `Homepage`, `Loader`, or `SidebarMenuItem`.
 
-- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that defines how your Component looks and behaves.
+- The second argument is a _Component configuration object_, represented as an `object literal`. This Component configuration object can contain a predefined set of key-value pairs, that define how your Component looks and behaves.
 
-Some of the common used Component configuration options include:
+Some of the commonly used Component configuration options include:
 
    - `template`: to define the template for the component.
    - `state`: to specify the component instance's internal state.

package/docs/essentials/displaying_images.md

@@ -25,7 +25,7 @@ For the best performance, it's important to keep your source images as small as
 
 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.
+By default, all Elements with a `src` attribute get a solid white background, with the result that the actual colors of the image will be shown.
 
 ```xml
 <Element
@@ -66,4 +66,4 @@ Considering the template above you would do something like the following in the
 }
 ```
 
-The `loaded` event receives the images dimensions as it's argument and the `error` event receives an error message explaining the failure.
+The `loaded` event receives image dimensions as its argument and the `error` event receives an error message explaining the failure.

package/docs/essentials/displaying_text.md

@@ -19,19 +19,19 @@ You can use the Text-tag anywhere in your template, without the need to explicit
 
 ### Available attributes on the Text tag
 
-The Text-tag accepts the following of attributes:
+The Text-tag accepts the following attributes:
 
-- `content` - the text to be displayed. Can be a hardcoded text, a dynamic value or a reactive value
+- `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))
+- `color` - the color to display for the text, defaults to `white` and can be any of the supported Blits color formats (HTML, hexadecimal 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
+- `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 attribute 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
+- `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 attributes
 - `textoverflow` - the suffix to be added when text is cropped due to bounds limits, defaults to `...`
 
 
@@ -39,23 +39,23 @@ The Text-tag accepts the following of attributes:
 
 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.
+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.
+ 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.
+The `font`-attribute on the `<Text>`-tag is used to 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.
+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`).
+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:
+Just add a new font object with the necessary details:
 
 ```js
   fonts: [

package/docs/essentials/element_attributes.md

@@ -4,14 +4,14 @@
 
 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 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.
+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
 
 In order to position and set the dimensions of an Element, the following attributes can be used.
 
-  - `x` - the x position of the Element in pixels, relative to it's parent - allows negative values and decimals
-  - `y` - the y position of the Element in pixels, relative to it's parent - allows negative values and decimals
+  - `x` - the x position of the Element in pixels, relative to its parent - allows negative values and decimals
+  - `y` - the y position of the Element in pixels, relative to its parent - allows negative values and decimals
   - `z` - the z index of the element (optionally `zIndex` can be used as an alias)
   - `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)
@@ -40,9 +40,9 @@ And the percentage specified for `h` and `y` will use the _height_ (`h`) of the
 
 ### Colors
 
-By default Elements have a transparent background color. The `color` attribute can be used to give an Element a color.
+By default, Elements have a transparent background color. The `color` attribute can be used to give an Element a color.
 
-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.
+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 converted in a way the Lightning 3 renderer can understand.
 
@@ -83,9 +83,9 @@ Again, you can use "normal" notation for the colors (like hexadecimal or rgba) a
 
 ### Alpha and visibility
 
-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 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 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">
@@ -107,13 +107,13 @@ The rotation of an Element is also automatically applied to any children down th
 
 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.
+This attribute either accepts a single numeric value for scaling evenly across 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 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_.
 
-Similar to rotation, scale is also applied recursively to children down the tree of the Element that has it's `scale` attribute set.
+Similar to rotation, scale is also applied recursively to children down the tree of the Element that has its `scale` attribute set.
 
 ```xml
 <Element w="200" h="200" color="blue" scale="0.5" />
@@ -123,13 +123,13 @@ Similar to rotation, scale is also applied recursively to children down the tree
 
 ### Mounting point
 
-For advanced positioning the `mount` attribute can come in handy. By default when you set the `x` and `y` position of an Element, the _top-left_ corner will be set to that position. But in some cases you may want to align the position starting at a different corner, or even any arbitrary point in between.
+For advanced positioning, the `mount` attribute can come in handy. By default when you set the `x` and `y` position of an Element, the _top-left_ corner will be set to that position. But in some cases, you may want to align the position starting at a different corner, or even any arbitrary point in between.
 
 The `mount` attribute accepts an _object literal_ that allows you to precisely control the mount position on the _x-axis_ and the mount position on the _y-axis_. The default value is `{x: 0, y: 0}`, which refers to the _top-left_ corner.
 
 In order to align the position starting at the _bottom-right_ corner, we would set `mount` to `{x: 1, y: 1}` and `{x: 0.5, y: 0.5}` would align the position at the _center_ of the Element.
 
-If you omit either the `x` or the `y` key from the _object literal_, it's value will default to `0`.
+If you omit either the `x` or the `y` key from the _object literal_, its value will default to `0`.
 
 In the case where the `x` and `y` values are the same (i.e. centering with `{x: 0.5, y: 0.5}`), you can also just supply a single value (`mount="0.5"`) instead of the object literal notation.
 
@@ -143,7 +143,7 @@ In the case where the `x` and `y` values are the same (i.e. centering with `{x:
 
 The pivot point of an Element comes into play when it's rotated or scaled. The pivot point defaults to the _center_ of the Element, which means that when setting `rotation` it rotates around the middle. And when the Element is scaled it scales from the center out.
 
-But sometimes you may want rotate around the left corner, or scale from the right side out. This can be controlled by adding the `pivot` attribute to the Element and, similar to the `mount` attribute, specify an _object literal_ with a `x` and a `y` key.
+But sometimes you may want to rotate around the left corner, or scale from the right side out. This can be controlled by adding the `pivot` attribute to the Element and, similar to the `mount` attribute, specify an _object literal_ with an `x` and a `y` key.
 
 Both `y` and `x` values should be anything between `0` and `1`, where `{x: 0, y: 0}` sets the pivot point to the _top-left_ corner and `{x: 1, y: 1}` refers to the _bottom-right_ corner. The default pivot value is `{x: 0.5, y: 0.5}` (i.e. the center) and if you omit `x` or `y` in your pivot object, it will default to `0.5`.
 
@@ -156,4 +156,10 @@ 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="700" pivot="0.9" rotation="42" />
 ```
 
-<!-- ### Clipping -->
+### Clipping / overflow
+
+By default contents inside an Element (i.e. child Elements) will overflow the boundaries of the parent, even when you give the parent Element fixed dimensions.
+
+In order to contain / cut off the content inside an Elements' `w` and `h`, you can add the `clipping="true"`-attribute. Setting `clipping` to `false` restores the default behaviour of content overflowing.
+
+Alternatively you can also use the `overflow`-attribute (and pass it `true` or `false`), which works similar to clipping just mapped inversly (i.e. `overflow="false"` ensures content that surpasses the parent dimensions is clipped-off).

package/docs/essentials/template_syntax.md

@@ -4,11 +4,11 @@
 
 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).
+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.
+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).
 
@@ -40,13 +40,13 @@ 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_.
+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.
+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.
 
@@ -54,15 +54,15 @@ For more complex logic, it's recommended to abstract this into a [Component meth
 
 ## 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.
+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 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.
+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.
+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.
+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.