@lightningjs/blits 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v1.4.0
+
+_16 sept 2024_
+
+- Added support for `fit` attribute to enable resizeModes for images (cover, contain)
+- Added priority parameter for event emitters + ability to stop propagation
+- Added Global App State plugin
+- Added Theme plugin
+- Standardized built-in utility methods (i.e. focus, select, setTimeout, etc.) to all be prefixed with a `$`.
+- Added support for triggering nested state variables with dot-notation (i.e `foo.bar.bla`)
+- Added support for watching nested state variables (i.e `foo.bar.bla`)
+- Fixed bug with Log plugin not picking up on `debugLevel` setting
+- Fixed bug when using hex-colors in an effect
+- Upgraded to latest version of the renderer (2.1.1)
+
+## v1.3.1
+
+_27 aug 2024_
+
+- Moved `this.$log` functionality to a plugin, which delays the instantation and allows it to pick up launch settings (bug fix)
+
 ## v1.3.0
 
 _19 aug 2024_

package/docs/_sidebar.md

@@ -17,6 +17,7 @@
   - [Hooking into lifecycle events](/components/lifecycle_events.md)
   - [Handling User input](/components/user_input.md)
   - [Methods](/components/methods.md)
+  - [Utility methods](/components/utility_methods.md)
 - Transitions and Animations
   - [Transitions](/transitions_animations/transitions.md)
 - Built-in components
@@ -25,3 +26,5 @@
 - Plugins
   - [Text-to-Speech / Announcer](/plugins/text-to-speech-announcer.md)
   - [Language](/plugins/language.md)
+  - [Theme](/plugins/theme.md)
+  - [Global App State](/plugins/global_app_state.md)

package/docs/components/utility_methods.md

@@ -0,0 +1,280 @@
+# 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)
+      })
+    },
+  }
+})
+```
+
+## 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 simular 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 mannually 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() {
+    interval: null,
+    secondCount: 0,
+    minuteCount: 0,
+  },
+  hooks: {
+    init() {
+      this.interval = this.$setInterval(() => {
+        console.log(`${secondCount} second(s) have passed`)
+      }, 1000)
+
+      this.$setInterval(() => {
+        console.log(`${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/plugins/global_app_state.md

@@ -0,0 +1,77 @@
+# Global App State plugin
+
+Each Blits Component has its own, internal component state that is reactive and can automatically trigger updates in the template upon changes. The internal state is fully encapsulated, which ensures predictable component state and promotes a pattern of clear separation of concerns.
+
+But a Component usually doesn't live on its own, instead it's part of a bigger App. And there may arise a need for components to exchange data - intercomponent communication in other words.
+
+Blits offers the option to _emit_ and _listen_ to events, as explained in the section on Blits [utility methods](../components/utility_methods.md). For simple use cases, this is a convenient method to pass data along. But when used extensively, it may be easy to lose track of data flows.
+
+For more advanced cases, Blits offers an optional Global App State plugin that will act as a global state store that all components have direct access to. It's a simple implementation, focused on providing a _performant_ and _easy to use_ solution for global state. It's not a full flux / redux style state management solution, as we know from experience that these solutions (while very useful and cool), may lead to performance issues on low-end devices.
+
+## Registering the plugin
+
+The Global App state plugin is provided in the core Blits package, but as it's an _optional_ plugin it first needs to be registered.
+
+The plugin can be imported from Blits and registered in the App's `index.js`, as demonstrated in the example below.
+
+Make sure to place the `Blits.Plugin()` method _before_ calling the `Blits.Launch()` method.
+
+```js
+// index.js
+
+import Blits from '@lightningjs/blits'
+// import the app state plugin
+import { appState } from '@lightningjs/blits/plugins'
+
+import App from './App.js'
+
+// Use the Blits App State plugin
+Blits.Plugin(appState, {
+  loggedIn: false,
+  user: {
+    id: null,
+    name: '',
+    lastname: ''
+  },
+  languages: ['en', 'nl', 'pt', 'es'],
+})
+
+
+Blits.Launch(App, 'app', {
+  // launch settings
+})
+```
+
+### State object
+
+When registering the Global App State plugin, you pass it a state object as the second argument. This is a plain object literal that will be converted into a _reactive_ object, and is used to keep track the global state variables.
+
+The newly created Global App state works exactly the same as an internal Component state. You can read values and you can directly change values. And when you do change a value, it automatically triggers reactive updates. Either via reactive attributes in the template, or in the form of watchers / computed values in the Component logic.
+
+### Using global app state in a Component
+
+Any variable in the Global App state can be used directly in the template, much like a local Component state. Changing values in the global app state also works exactly the same as updating the internal component state.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text :content="$$appState.loggedIn ? $$appState.user.name : 'Not logged in'" />
+    </Element>
+  `,
+  input: {
+    enter() {
+      this.$appState.user.name = 'John'
+      this.$appState.loggedIn = true
+    }
+  },
+})
+```
+
+Note that in the template definition, 2 consecutive dollars signs are used (`$$appState`). The first `$`-sign is used
+to refer to the Component scope, as with any other state variable or computed property referenced in the template.
+
+The second `$`-sign is needed, since the appState plugin itself is prefixed with a dollar sign, to prevent accidental naming collisions.
+
+In order to read or update variables on the global app state inside the component logic, you can access the entire state via `this.$appState`.
+

package/docs/plugins/theme.md

@@ -0,0 +1,176 @@
+# Theme plugin
+
+Blits comes with a built-in, lightweight *Theme* plugin, that can be used to easily add theming capabilities to an App.
+
+The Blits Theme plugin provides the option to do real time theme switching, with inheritance from a base theme for missing values.
+
+## Registering the plugin
+
+The Theme plugin is part of the core Blits package, but it's an optional plugin that needs to be registered in the App's `index.js`,
+as demonstrated in the example below.
+
+Make sure to place the `Blits.Plugin()` method _before_ calling the `Blits.Launch()` method
+
+```js
+// index.js
+
+import Blits from '@lightningjs/blits'
+// import the theme plugin
+import { theme } from '@lightningjs/blits/plugins'
+
+import App from './App.js'
+
+// Use the Blits Theme plugin
+Blits.Plugin(theme, {
+  // theme configuration object
+})
+
+
+Blits.Launch(App, 'app', {
+  // launch settings
+})
+```
+
+### Configuration
+
+The Theme plugin requires configuration that specifies the theming definition(s).
+
+For simple use cases, with one single theme where you just want to abstract and centralize the styling information for an App,
+the configuration object can be a simple object that specifies a theme definition.
+
+A theme definition is a completely freeform object literal with key values pairs. It can be organized and constructed however makes most sense for the App. See below an example for inspiration:
+
+```js
+Blits.Plugin(theme, {
+  colors: {
+    primary: '#16a34a',
+    secondary: '#2563eb',
+    highlight: '#ec4899'
+  },
+  radius: {
+    small: 4,
+    medium: 8,
+    large: 12
+  },
+  fontSizes: {
+    h1: 80,
+    h2: 64,
+    body: 42
+  }
+})
+```
+
+> While it's possible to create deeply nested structures in the theme definition, it is recommended to limit the level of nesting for performance reasons.
+
+
+When an App has more than 1 theme, the _advanced configuration_ setup can be used. This configuration object can contain the following 3 keys:
+
+- `themes` - an object with multiple theme definitions (required)
+- `base` - the name of the base theme in the `themes`-object, that other themes can inherit from (optional, defaults to `default`)
+- `current` - the name of current theme to be used (optional, defaults to `default`)
+
+```js
+Blits.Plugin(theme, {
+  themes: {
+    // Base theme
+    base: {
+      colors: {
+        primary: '#16a34a',
+        secondary: '#2563eb',
+        highlight: '#ec4899'
+      },
+      radius: {
+        small: 4,
+        medium: 8,
+        large: 12
+      },
+      fontSizes: {
+        h1: 80,
+        h2: 64,
+        body: 42
+      }
+    },
+    // Dark mode theme
+    dark: {
+      colors: {
+        primary: '#042f2e',
+        secondary: '#082f49'
+      }
+    },
+    // Theme with larger font sizes
+    large: {
+      fontSizes: {
+        h1: 160,
+        h2: 124,
+        body: 84
+      }
+    }
+  },
+  base: 'base',
+  current: 'large'
+})
+```
+
+In the definition above we've specified 3 different themes: `base`, `dark` and `large`. The dark and large theme are not complete definitions,
+which mean that they will inherit missing values from the base theme.
+
+
+## Getting theme values
+
+With the configuration out of the way, let's look at how to use the specified theme values in an App.
+
+The Theme plugin will be available in every component under the `this.$theme`-namespace. It exposes a `get()` method than can be used to
+retrieve values from the currently active theme definition.
+
+The `this.$theme.get()`-method accepts a `key`-argument, using _dot-notation_ (i.e. `fonts.large.lineheight`) to reference items in the theme definition. An optional second argument can be provided as a fallback value, in case the key is missing in the theme (as well as in the base theme).
+
+Inside of the template, the `this.$theme.get()`-method can be referenced as `$$theme.get()`. The first `$`-sign is used
+to refer to the Component scope (as with any other state variable or computed property in Blits) and the second `$`-sign is the prefix of
+the Theme plugin itself.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text content="Hello world"
+        :color="$$theme.get('colors.primary', 'blue')"
+        :size="$$theme.get('fontSizes.body')"
+      />
+    </Element>
+  `,
+  computed: {
+    highlight() {
+      return this.$theme.get('colors.highlight')
+    }
+  },
+})
+```
+
+## Changing themes
+
+In case you have specified multiple themes, using the advanced configuration, it is possible to do real-time theme switching.
+
+Besides the `get()` method, the Theme plugin also exposes a `set()`-method, to change the currently active theme. The `this.$theme.set()`-method accepts the name of the theme as its first argument.
+
+```js
+Blits.Component('MyComponent', {
+  template: `
+    <Element>
+      <Text content="Hello world"
+        :color="$$theme.get('colors.primary', 'blue')"
+        :size="$$theme.get('fontSizes.body')"
+      />
+    </Element>
+  `,
+  input: {
+    up() {
+      this.$theme.set('dark')
+    },
+    down() {
+      this.$theme.set('default')
+    }
+  },
+})
+```
+
+All attributes referencing the Theme plugin that are marked as _reactive_ (i.e. those prefixed with a `:`), will update instantly when changing the theme.

package/docs/sidebar.json

@@ -75,6 +75,10 @@
       {
         "text": "Methods",
         "link": "/components/methods"
+      },
+      {
+        "text": "Utility methods",
+        "link": "/components/utility_methods"
       }
     ]
   },
@@ -110,6 +114,14 @@
       {
         "text": "Language",
         "link": "/plugins/language"
+      },
+      {
+        "text": "Theme",
+        "link": "/plugins/theme"
+      },
+      {
+        "text": "Global App State",
+        "link": "/plugins/global_app_state"
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.0.2",
-    "@lightningjs/renderer": "^1.0.0",
+    "@lightningjs/renderer": "^2.1.2",
     "execa": "^8.0.1",
     "kolorist": "^1.8.0",
     "ora": "^7.0.1",

package/src/component/base/events.js

@@ -20,15 +20,16 @@ import eventListeners from '../../lib/eventListeners.js'
 export default {
   $emit: {
     value: function (event, params) {
-      eventListeners.executeListeners(event, params)
+      // returning if all listeners executed
+      return eventListeners.executeListeners(event, params)
     },
     writable: false,
     enumerable: true,
     configurable: false,
   },
   $listen: {
-    value: function (event, callback) {
-      eventListeners.registerListener(this, event, callback)
+    value: function (event, callback, priority = 0) {
+      eventListeners.registerListener(this, event, callback, priority)
     },
     writable: false,
     enumerable: true,

package/src/component/base/index.js

@@ -18,7 +18,6 @@
 import methods from './methods.js'
 import scheduling from './timeouts_intervals.js'
 import events from './events.js'
-import log from './log.js'
 import router from './router.js'
 import announcer from './announcer.js'
 import utils from './utils.js'
@@ -26,7 +25,7 @@ import symbols from '../../lib/symbols.js'
 
 export default Object.defineProperties(
   {
-    [symbols['pluginsRegistered']]: false,
+    [symbols['launched']]: false,
   },
-  { ...methods, ...scheduling, ...events, ...log, ...router, ...announcer, ...utils }
+  { ...methods, ...scheduling, ...events, ...router, ...announcer, ...utils }
 )