@lightningjs/blits 1.30.2 → 1.31.0

package/docs/components/methods.md

@@ -1,45 +0,0 @@
-# Methods
-
-Within a Blits component, you have quite some freedom where to put specific logic.
-
-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.
-
-If you notice that you're duplicating logic in these different places, or if you just like to keep all your business logic nicely grouped together, you can move these business logic functions under the `methods` key of the _Component configuration object_.
-
-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 to `internal` state and `props`, there is no need to prefix with `methods`, for easy access.
-
-```js
-export default Blits.Component('Carousel', {
-  template: `
-    <Element>
-      <!-- .... -->
-    </Element>
-  `,
-  state() {
-    return {
-      items: [],
-      page: 0
-    }
-  },
-  hooks: {
-    ready() {
-      this.fetchData()
-    }
-  },
-  input: {
-    down() {
-      this.page++
-      this.fetchData()
-    }
-  },
-  methods: {
-    async fetchData() {
-      this.items = await API.get(['movies', 'tvshows', 'documentaries'], this.page)
-    },
-  }
-})
-```

package/docs/components/props.md

@@ -1,56 +0,0 @@
-# Props
-
-Components in Blits have their own [internal state](./component_state.md) and logic, and as such a Component is self-contained. However, as each component is part of a larger App scope, they may need to display different behaviors or appearances based on the rest of the app.
-
-To achieve this, components can receive `props` from their parent component.
-
-## Defining and passing props
-
-In the Component configuration object, you can specify exactly which props a component accepts. These props are passed to the component via attributes in the parent component's template. Any attributes that are not explicitly defined as a prop will be ignored.
-
-The `props` key in the Component configuration object should be an `Array`, where each item corresponds to a prop that the component can accept.
-
-The simplest way to define props is to just list their names within the `props` array:
-
-```js
-{
-  props: ['x', 'color', 'index', 'alpha']
-}
-```
-
-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 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).
-
-## Advanced usage
-
-For more advanced usage, you can define props using an array with an `object` for each prop, instead of just a string with the accepted name. Within each prop object, you can:
-
-- Specify a _default value_ for the prop if it's omitted.
-- _Validate_ the value of the prop based on certain criteria.
-- Mark the prop as _required_.
-- Apply a `cast` function to modify the value passed as a prop.
-
-As you can see in the following example, you can mix and match the simple string notation with the advanced object notation within the same `props` array.
-
-
-```js
-export default Blits.Component('MyComponent', {
-  // ...
-  props: [
-    'color',
-    {
-      key: 'alpha',
-      default: 0.5,
-      required: true,
-      validate(v) {
-        return v <= 1 && v >= 0;
-      },
-      cast: Number
-    }
-  ]
-})
-```

package/docs/components/user_input.md

@@ -1,186 +0,0 @@
-# Handling User Input
-
-In order to allow users to interact with your app, you will want to capture and handle _user input_. If you are developing a TV based app this will often be key input via a remote control.
-
-Blits offers an intuitive and straightforward interface to handle key input in Components.
-
-## Focus
-
-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.
-
-The component that has focus, is the one that is responsible for handling the user input at that moment.
-
-For example, when a user clicks the _right_ or _left_ button while a _Poster Component_ has focus, it is that instance of the Poster Component that will _receive_ the first key press event.
-
-## Configuring Input Handling
-
-Within the Component configuration object, the `input` key is used to define how the component should react to specific key presses when it has focus. The `input` key should be an `object literal` of `functions` for each input event that the component wants to handle.
-
-Each function corresponds to a _key press name_, such as `up`, `down`, `enter`, `space`, `back`, `1`, `2`, `a` etc and each function defined in the `input` object, receives the full `InputEvent` object as its first argument.
-
-```js
-export default Blits.Component('MyComponent', {
-  // ...
-  input: {
-    up(e) {
-      // Logic to execute when users press up
-    },
-    down(e) {
-      // Logic to execute when users press down
-    },
-    enter(e) {
-      // Logic to execute when users press enter
-    },
-  }
-}
-```
-
-## Catch-All Handling
-
-To allow a focused component to respond to any key and act as a _catch-all_, you can add an `any()` function to the input object. As it receives the `InputEvent` object as the first argument, you can abstract the key press in there and handle (or ignore) it as you wish.
-
-```javascript
-{
-  input: {
-    any(e) {
-      // Logic to execute for any key press
-    },
-  }
-}
-```
-
-## Event Handling Chain
-
-If the currently focused component does not handle a key press, Blits will traverse up the component hierarchy, checking for any _parent_ component that does have a function defined for that key press in the `input`-key. This input event handling chain continues until it reaches the root Application component.
-
-When a component handles a key press by having a corresponding function specified, said component receives focus, and the event handling chain stops by default. However, if you want the input event to propagate up the hierarchy further, you can move the focus to the parent element and pass the `InputEvent` object on in that function call.
-
-```javascript
-{
-  input: {
-    enter() {
-      // Give focus to the parent
-      this.parent.focus();
-    },
-    back(e) {
-      // Give focus to the parent and let the user input event bubble
-      this.parent.focus(e);
-    },
-  }
-}
-```
-
-## Intercepting key input
-
-In addition to the Event handling chain explained above. Blits offers the option to _intercept_ key presses at the root level of the Application, before they reach the currently focused Component. This can be useful in certain situation where you want to globally disable all key presses, or when implementing an override key press handler.
-
-The `intercept()` input-method can only be implemented in the `Blits.Application`-component. When present, the method acts as a _catch-all_ method, and will be executed for _all_ key presses. It receives the `KeyboardEvent` as its argument, allowing you to execute logic based on the key being pressed.
-
-Only when the `intercept()` input-method returns the `KeyboardEvent` (possibly modified), the keypress will continue to be handled (by the currently focused Component).
-
-The `intercept`-method can also be an asynchronous method.
-
-## Key-up handling
-
-The functions specified in the `input` configuration are invoked when a key is _pressed down_ (i.e. the `keydown` event listener). But sometimes you may also want to execute some logic when a key is _released_ (i.e. the `keyup` event listener).
-
-Instead of introducing a separate key on the Component configuration object for key release callbacks, Blits relies on the concept that a `keyup` event is always preceded by a `keydown` event.
-
-Following this logic, whenever you return a function in an input (key down) handler, this function will be executed upon release (i.e. the `keyup` event) of that key .
-
-When an input key is being a hold down, it will execute the key down handler multiple times. Upon key release, only the last returned key up callback function will be executed.
-
-
-```javascript
-Blits.Component('MyComponent', {
-  //
-  input: {
-    enter() {
-      // execute logic on key down
-      this.pressedEnter = true
-      return () => {
-        // execute logic on key up
-        this.pressedEnter = false
-      }
-    },
-    space(e) {
-      // not logic on key down
-      return () => {
-        // only execute logic on key up
-        console.log('Space key released')
-      }
-    },
-    left() {
-      // some logic on key down here ..
-      this.leftHold = true
-      // return a reference to a Component method
-      // (instead of creating a new function on the fly)
-      return this.leftKeyUp
-    }
-  },
-  methods: {
-    leftKeyUp() {
-      console.log('Left key up')
-      this.leftHold = false
-    }
-  }
-}
-```
-
-## Custom Keycode mapping
-
-Blits comes with a default keycode mapping. This mapping is a sensible default that works in your desktop browser and with most RDK based devices.
-
-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 instantiate the App via the `Blits.Launch` function, we can add an extra key, called `keymap`, to the _settings object_.
-
-The `keymap` should contain an object literal, where you map a `key` or `keyCode` (from the `KeyboardEvent`) to an event name that you can use in your Components.
-
-> You can use a site like [keyjs.dev](https://keyjs.dev/) to find the appropriate key and keyCode for your device
-
-```js
-// src/index.js
-Blits.Launch(App, 'app', {
-  w: 1920,
-  h: 1080,
-  //...
-  keymap: {
-    // switch left and right using the key
-    ArrowLeft: 'right',
-    ArrowRight: 'left',
-    // switch up and down using the keyCode
-    38: 'down',
-    40: 'up',
-    // register new handlers
-    '.': 'dot', // dot() can now be used in the input object
-    // key code for letter 's'
-    83: 'search' // search() can now be used in the input object
-  }
-})
-```
-
-The custom keymap object will be merged with the default key mapping, that looks like this:
-
-```js
-const defaultKeyMap = {
-  ArrowLeft: 'left',
-  ArrowRight: 'right',
-  ArrowUp: 'up',
-  ArrowDown: 'down',
-  Enter: 'enter',
-  ' ': 'space',
-  Backspace: 'back',
-  Escape: 'escape',
-  37: 'left',
-  39: 'right',
-  38: 'up',
-  40: 'down',
-  13: 'enter',
-  32: 'space',
-  8: 'back',
-  27: 'escape',
-}
-```

package/docs/components/utility_methods.md

@@ -1,320 +0,0 @@
-# Utility methods
-
-Besides the methods that are specified in the Component configuration object, each Blits Component comes with a number of
-_utility methods_ built in.
-
-Utility methods are prefixed with a `$`-sign, to clearly indicate they are _framework provided_ methods, that are _not private_, but
-intended to be _used by the developer_. The `$`-prefix also helps prevent accidental naming collisions.
-
-### $select
-
-`this.$select()` is used to search for child Elements and Components by reference (`ref`).
-
-The `$select()`-method accepts a string pointing to a reference as it's only argument, and returns the Element or Component that
-matches that `ref`. In order to make an Element or Component findable, the `ref`-attribute should be provided on said Element of Component
-in the template.
-
-```js
-export default Blits.Component('MyComponent', {
-  components: {
-    Button,
-  },
-  template: `
-    <Element>
-      <Element w="1920" h="5" color="green" ref="topBorder" />
-      <Button text="Button 1" ref="btn1" y="100" />
-      <Button text="Button 2" ref="btn2" y="200" />
-      <Button text="Button 3" ref="btn3" y="200" />
-    </Element>
-  `,
-  hooks: {
-    ready() {
-      const topBorderElement = this.$select('topBorder')
-      const button2 = this.$select('btn2')
-    }
-  }
-})
-```
-
-> As the `this.$select()` gives direct access to an Element or a Component, it allows the developer to directly interact with it. There are valid use cases, but direct manipulation of Elements, calling methods and changing properties on a Component comes with risks. It circumvents the whole structure of reactivity and props communication built into Blits, and can lead to unexpected situations or anti-patterns. So use with care!
-
-### $focus
-
-The `$focus()`-method can be used to set the focus to a Component instance. It can either be called on the instance itself, in order to "claim"
-the focus. But more often it will be used to delegate the focus from on Component to another.
-
-> It is important to understand that only a Component can receive focus in Blits. Elements don't have a focus method, and also have no way of reacting to focus changes (because they have no hooks etc.).
-
-Often focus will be passed onto a child component, for example in the case of a list or swimlane, where you want to delegate the focus to a poster.
-In this case the focus method will be used in combination with `this.$select()` to first select the desired child Component by ref, and subsequently call the `$focus()` method on that Component.
-
-```js
-export default Blits.Component('MyComponent', {
-  components: {
-    Button,
-  },
-  template: `
-    <Element>
-      <Element w="1920" h="5" color="green" ref="topBorder" />
-      <Button text="Button 1" ref="btn1" y="100" />
-      <Button text="Button 2" ref="btn2" y="200" />
-      <Button text="Button 3" ref="btn3" y="200" />
-    </Element>
-  `,
-  state() {
-    focusIndex: 1
-  },
-  input: {
-    down() {
-      this.focusIndex--
-      const button = this.$select(`btn${this.focusIndex}`)
-      if(button) {
-        button.$focus()
-      }
-    },
-    up() {
-      this.focusIndex++
-      const button = this.$select(`btn${this.focusIndex}`)
-      if(button) {
-        button.$focus()
-      }
-    },
-  }
-})
-```
-
-Another frequent case is that focus is passed on to the parent Component. The parent component is available on the Component scope as `this.parent`. So passing the focus to the parent is as simple as calling `this.parent.$focus()`.
-
-The `$focus`-method accepts an optional `event` parameter, which is of the type `KeyboardEvent`. When the `event` parameter is provided, not only will the selected Component receive focus, but the input event will be emitted again on the component that just received focus.
-
-This can be used to _bubble up_ input events (specified in the `input` key of the component configuration object) and helps to create a smooth experience, preventing a user to click multiple times.
-
-
-### $trigger
-
-Blits has reactivity built-in, which means that re-renders in the template, as well as watchers and computed properties, are automatically fired whenever a state value changes. But sometimes you may want trigger the side effects of a state values change, without actually changing the value. This often is useful when a Component first receives focus and you want to ensure that the default state values are applied.
-
-Instead of setting a value to `null` and then setting it back to the initial value (which would trigger side effects), the `this.$trigger()` method can be used. The method accepts the name of the state variable as its argument.
-
-```js
-export default Blits.Component('MyComponent', {
-  state() {
-    focusIndex: 1
-  },
-  watchers: {
-    focusIndex(v) {
-      console.log('I trigger when focusIndex changes')
-    }
-  },
-  hooks: {
-    focus() {
-      // even though focusIndex didn't change
-      // the watcher on focusIndex will be fired
-      this.$trigger('focusIndex')
-    }
-  }
-})
-```
-
-## Emitting events and passing data
-
-### $emit
-
-When working with Components in Blits you will often want to send data from one to another. In the case of (direct) child Component, using
-props is the defacto way for inter-component communication.
-
-For passing data from a child to a parent component, you may be tempted to use the `this.parent` reference and change the state directly. While this works, it does create a strict dependency on the parent, meaning the child Component only works properly when tied directly to a specific parent. This reduces reusability of Components and may cause limitations or problems later on.
-
-Instead the `this.$emit()` method can be used, which is available on each Component as a utility function. It's designed to easily emit data to anywhere in an App. The first argument is the `name` of the event that will be emitted (i.e. `changeBackground`) and optionally a second argument with additional `data` can be passed.
-
-```js
-export default Blits.Component('MyComponent', {
-  input: {
-    enter() {
-      // sending a activate event, without any additional data
-      this.$emit('activate')
-    },
-    space() {
-      // sending a changeBackground event, with additional data
-      this.$emit('changeBackground', {
-        img: './assets/background1.jpg',
-        delay: 400
-      })
-    }
-  }
-})
-```
-
-### $listen
-
-The `$listen` utility method (which is available on each Blits Component) is designed to listen for events emitted by `this.$emit()`.
-Any Component can subscribe to any event emitted and as such a flexible system of passing data around can be constructed.
-
-The first argument of the `$listen()`-method is the event `name` to listen for, and the second argument is a `callback` to be executed
-anytime the event occurs. When the event is emitted with additional data, it's passed as the first argument in the callback.
-
-Generally the listeners are registered in the Component `ready` or `init` hook. Blits automatically takes care of deregistering the listeners whenever a Component is destroyed.
-
-```js
-export default Blits.Component('MyComponent', {
-  hooks: {
-    init() {
-      // activate event without any additional value
-      this.$listen('activate', () => {
-        console.log('activated')
-        // set a text state valuye
-        this.text = 'We are active!'
-      })
-
-      // change background event
-      this.$listen('changeBackground', (data) => {
-        setTimeout(() => {
-          this.backgroundImage = data.img
-        }, data.delay)
-      })
-    },
-  }
-})
-```
-
-### $unlisten
-
-The `$unlisten` utility method (which is available on each Blits Component) is designed to remove event listeners that were previously registered using `$listen()`. This method helps in managing event listeners manually when needed.
-
-The first argument of the `$unlisten()` method is the event `name` to stop listening for. This ensures that all listeners for the specified event are removed from the component.
-
-Generally, you might not need to call `$unlisten()` manually, as Blits automatically deregisters listeners when a Component is destroyed. However, it can be useful in scenarios where you need to stop listening for events before the Component is destroyed.
-
-```js
-export default Blits.Component('MyComponent', {
-  hooks: {
-    init() {
-      this.activateListener = () => {
-        console.log('activated')
-        this.text = 'We are active!'
-      }
-
-      this.changeBackgroundListener = (data) => {
-        setTimeout(() => {
-          this.backgroundImage = data.img
-        }, data.delay)
-      }
-
-      // Register listeners
-      this.$listen('activate', this.activateListener)
-      this.$listen('changeBackground', this.changeBackgroundListener)
-    },
-    unfocus() {
-      // Remove listeners when Component is unfocused
-      this.$unlisten('activate')
-      this.$unlisten('changeBackground')
-    }
-  }
-})
-```
-
-## Timeouts
-
-Setting a timeout is a typical way in JS to execute functionality with a delay. But timeouts can also be a common cause of
-memory leaks.
-
-As long as the timeout is still pending it, it will hold on to references which can prevent a proper garbage collection from happening. That's why it's important to clear timeouts when destroying a component.
-
-Blits comes with some built-in methods to register and clear timeouts. Under the hood these methods use regular timeouts, but using the Blits built-in methods ensures that timeouts properly are cleared whenever a component is being disposed.
-
-### $setTimeout
-
-The `this.$setTimeout()`-method creates a timeout, using a thin wrapper around the `window.setTimeout()` method. The first argument is the `callback` to be executed after the `delay` specified in the second argument. The method returns a `timeout id`, which can be used to mannually clear the timeout.
-
-### $clearTimeout
-
-The `this.$clearTimeout()`-method is a thin wrapper around the `window.clearTimeout()`-method. By passing in the `id` of a timeout, it will clear and remove the timeout.
-
-### $clearTimeouts
-
-The `this.$clearTimeouts()`-method is a utility method that is used to clear all the timeouts created via the `this.$setTimeout()` method in one go. The method doesn't require to pass any timeout ids. This method is automatically called when destroying a Component, and with that it prevents memory leaks due to dangling timeouts.
-
-```js
-export default Blits.Component('MyComponent', {
-  state() {
-    timeout: null
-  },
-  hooks: {
-    init() {
-      this.timeout = this.$setTimeout(() => {
-        console.log('1 minute has passed!')
-      }, 60000)
-
-      this.$setTimeout(() => {
-        console.log('10 seconds have passed!')
-      }, 10000)
-    },
-    unfocus() {
-      // clear all timeouts when Component is unfocused
-      this.$clearTimeouts()
-    }
-  },
-  input: {
-    enter() {
-      // clear the timeout
-      this.$clearTimeout(this.timeout)
-    }
-  }
-})
-```
-
-## Intervals
-
-Timeouts are a great way to execute recurring logic, such as polling for updates or periodically updating an animation.
-
-But similar to timeouts, intervals (more specifically failing to clear them) are a common source of memory leaks - maybe even more than dangling timeouts.
-
-For this reason Blits has 3 built-in utility methods to help registering and clearing intervals.
-
-### $setInterval
-
-The `this.$setInterval()`-method create an interval, using a thin wrapper around the `window.setInterval()` method. The first argument is the `callback` to be executed after each interval `delay` specified in the second argument. The method returns an `interval id`, which can be used to manually clear the interval.
-
-### $clearInterval
-
-The `this.$clearInterval()`-method is a thin wrapper around the `window.clearInterval()`-method. By passing in the `id` of an interval, it will clear and remove the interval.
-
-
-### $clearIntervals
-
-The `this.$clearIntervals()`-method is a utility method that is used to clear all the intervals created via the `this.$setInterval()` method in one go. The method doesn't require to pass any interval ids. This method is automatically called when destroying a Component, and with that it prevents memory leaks due to dangling intervals.
-
-```js
-export default Blits.Component('MyComponent', {
-  state() {
-    return {
-      interval: null,
-      secondCount: 0,
-      minuteCount: 0,
-    }
-  },
-  hooks: {
-    init() {
-      this.interval = this.$setInterval(() => {
-        this.secondCount++
-        console.log(`${this.secondCount} second(s) have passed`)
-      }, 1000)
-
-      this.$setInterval(() => {
-        this.minuteCount++
-        console.log(`${this.minuteCount} minute(s) have passed`)
-      }, 60000)
-    },
-    unfocus() {
-      // clear all intervals when Component is unfocused
-      this.$clearIntervals()
-    }
-  },
-  input: {
-    enter() {
-      // clear the interval
-      this.$clearInterval(this.interval)
-    }
-  }
-})
-```

package/docs/components/watchers.md

@@ -1,34 +0,0 @@
-# Watchers
-
-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 an endless loop.
-
-Instead, Blits allows you to specify **watchers** to trigger functionality when certain variables change.
-
-## Using Watchers
-
-Within the `watch` key of the _Component configuration object_, you can define an object of _watcher functions_.
-
-The name of each function should correspond with the name of the state variable, the prop, or the computed property that you want to observe. Whenever the value of the observed target changes, the respective watcher function will be invoked.
-
-The watcher function receives two arguments: the _new value_ and the _old value_ of the observed property. This allows you to perform specific actions based on the changes.
-
-```javascript
-{
-  state() {
-    return {
-      alpha: 0.2
-    }
-  },
-  watch: {
-    alpha(value, oldValue) {
-      if(value > oldValue) {
-        // Execute some logic when the 'alpha' value increases
-      }
-    },
-  }
-}
-```
-
-In this example, whenever the value of state variable `alpha` changes, the `alpha` watcher function will be invoked. The function checks if the new value is greater than the old value and executes custom logic accordingly.

package/docs/essentials/application_root.md

@@ -1,19 +0,0 @@
-# Application root
-
-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.
-
-`src/App.js` will look something like this:
-
-```js
-import Blits from '@lightningjs/blits'
-
-export default Blits.Application({
-  template: `
-    <Element></Element>
-   `,
-})
-```