@lightningjs/blits 1.30.1 → 1.31.0

package/docs/plugins/language.md

@@ -1,172 +0,0 @@
-# Language plugin
-
-Blits comes with a built-in Language plugin, that can be used to add internationalization (i18n) to your App.
-
-The Blits Language plugin is a simple and lightweight implementation, closely modeled after the tried and tested Language plugin in the Lightning-SDK (for Lightning 2). It is designed to provide a flexible and easy way of translating texts to multiple languages, in a performant way.
-
-## Registering the plugin
-
-While the Language plugin is provided in the core Blits package, it's an _optional_ plugin that needs to be registered before you're able to use it. As such the Language plugin is _tree-shakable_, i.e. for Apps that don't have a need for translation functionality, the Language plugin will not be part of the final App bundle.
-
-The Language plugin should 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 language plugin
-import { language } from '@lightningjs/blits/plugins'
-
-import App from './App.js'
-
-// Use the Blits Language plugin and
-// optionally pass in a settings object
-Blits.Plugin(language, {
-  file: '/assets/translations.json', // file with translations
-  language: 'EN-us', // default language
-})
-
-
-Blits.Launch(App, 'app', {
-  // launch settings
-})
-```
-
-The Language plugin accepts an optional configuration object with 2 keys:
-
-- `file` - the JSON file with translations to be loaded at initialization
-- `language` - the default language to use
-
-After registration of the Language plugin, it will be available in each Blits Component as `this.$language`.
-
-## Translations file
-
-The most common way of defining a set of translations, is to use a dedicated JSON file, modeled after
-the following format:
-
-```json
-{
-    "nl-NL": {
-      "hello": "Hallo, alles goed?",
-      "bye": "Doei!",
-      "replacement": "Mijn naam is {first} {last}, ik ben {age} jaar"
-    },
-    "en-US": {
-      "hello": "Hello, how are you doing?",
-      "bye": "Goodbye!",
-      "replacement": "My name is {first} {last}, I'm {age} years old"
-    },
-    "fr-FR": {
-      "hello": "Bonjour, ça va?",
-      "bye": "Au revoir!",
-      "replacement": "Je m'appelle {first} {last}, j'ai {age} ans"
-    },
-    "de-DE": {
-      "hello": "Gutentag, wie geht's?",
-      "bye": "Tschüss!",
-      "replacement": "Mein Name ist {first} {last}, ich bin {age} Jahre alt"
-    }
-  }
-```
-
-Each top level key represents a language, which contains an object with translation key-value pairs. The language key
-doesn't require to be in a specific format, but it's recommended to use ISO-codes.
-
-When the JSON file is specified in the Plugin registration method, the language file is loaded automatically upon instantiation.
-
-In case you want to load the file with translations manually, you can use the `this.$language.load()`-method anywhere in a Component and pass in the path to the JSON file as the first argument.
-
-## Defining translations manually
-
-As an alternative to a JSON file with translations, you can also define translations directly via an object, using the `translations()`-method.
-
-The `this.$language.translations()`-methods accepts a translations object as it's first argument, following the same format as the JSON file. The method is typically used in an `init` or `ready` hook
-
-```js
-Blits.Component('MyComponent', {
-  // ...
-  hooks: {
-    init() {
-      this.$language.translations({
-        english: {
-          hello: "Hello",
-          world: "World"
-        },
-        italian: {
-          hello: "Ciao",
-          world: "Mondo"
-        }
-      })
-    }
-  },
-})
-```
-
-## Setting the language
-
-In order to set (or change) the current language, the `this.$language.set()`-method can be used, passing in the new language code (matching one of the languages defined in the translations).
-
-```js
-Blits.Component('MyComponent', {
-  // ...
-  input: {
-    enter() {
-      this.$language.set('pt-BR')
-    }
-  },
-})
-```
-
-## Getting the current language
-
-The current language can be retrieved via the `this.$language.language` property. It will return the currently set language code.
-
-## Translating
-
-The most important functionality in the Language plugin is translating. The Language plugin exposes a `translate()` method that takes as string to translate as it's first argument. It will return the translated value in the currently set language. If either the language or the string to translate can't be found, it will return the inputed string.
-
-The translate method can be used both inside the javascript business logic, but also directly in the template.
-
-```js
-Blits.Component('MyComponent', {
-  template: `
-    <Element>
-      <Text :content="$$language.translate('hello')" />
-      <Text y="100" :content="$$language.get()" />
-    </Element>
-  `,
-  hooks: {
-    ready() {
-      console.log(this.$language.translate('world'))
-    }
-  },
-})
-```
-
-Note that in the template definition 2 consecutive dollars signs are used (`$$language`). The first `$`-sign is used
-to refer to the Component scope, as with any other state variable or computed property refereced in the template.
-
-The second `$`-sign is needed, since the Language plugin itself is prefixed with a dollar sign on the Component scope as well (i.e `this.$language`).
-
-
-### Dynamic replacements
-
-The `tranlate()`-method also supports dynamic replacements. This allows you to specify variables inside your translation string, and replace them with dynamic values passed into the `translate()`-method.
-
-Replacements are marked in the translation value using _handlebars_, like so:
-
-```js
-{
-  replacements = "My name is {first} {last}, I'm {age} years old"
-}
-```
-
-Now when you call the `translate()`-method and pass in an object with dynamic values, those will be replaced
-in the final string accordingly:
-
-```js
-this.$language.translate('replacements', {name: 'John', last: 'Doe', age: 18})
-// result: My name is John Doe, I'm 18 years old
-```

package/docs/plugins/text-to-speech-announcer.md

@@ -1,120 +0,0 @@
-# Text-to-Speech / Announcer
-
-Blits comes with a built-in Text-to-Speech / Announcer functionality, to easily make your App more accessible. This is something that's often overlooked when developing an App, but having speech assistance integrated into your App is a huge deal for those users who are visually impaired.
-
-## Integrated with the router
-
-The Announcer in Blits is directly integrated with the router functionality. This means that through simple configuration, a descriptive message can be announced, when navigating from page to page, without the need for adding extra custom code.
-
-Just add an `announce` key in the configuration of your route, that contains the message you would like to be announced when visiting that route.
-
-```js
-const routes = [
-  // ...
-  {
-    path: '/settings',
-    component: Settings,
-    announce: "Welcome to the Settings page",
-  },
-  // ...
-]
-```
-
-## Custom announcement messages
-
-Furthermore, it's possible to speak out custom messages anywhere in your App logic, for example when a component receives focus, as a reaction to user input, or to announce error messages when a remote API call
-fails.
-
-Each component in Blits has a `this.$announcer.speak()` available, which accepts a `string` with the message to be announced.
-
-```js
-Blits.Component('MyComponent', {
-  // ...
-  hooks: {
-    focus() {
-      this.$announcer.speak('MyComponent just got focus')
-    }
-  },
-  keys: {
-    right() {
-      if(this.focused === this.items.length - 1) {
-        this.$announcer.speak('End of row reached')
-      } else {
-        //
-      }
-    }
-  }
-})
-```
-
-### Execute logic when done
-
-The `speak()`-function returns a promise that resolves when it's done speaking, or when it's interupted or errors out. The reason of the `speak()` method resolving is passed as an argument into the resolve function.
-
-```js
-this.$announcer.speak('Hello').then((reason) => console.log('Speaking hello finished', reason))
-```
-
-### Announcement queue
-
-The `speak()`-method places the messages in an announcement queue and then starts processing that queue. That means that when the queue is empty, it will instantly announce the messages passed. If there are other messages in the queue, the messages will be spoken when all previous messages are announced.
-
-Optionally you can set the politeness of a message to `assertive` and pass it a the second argument of the `speak()`-method.
-
-```js
-this.$announcer.speak('Very important message that should get priority', 'assertive')
-```
-
-This will place the message at the beginning of the queue, making in the first message to be announced after the current message (if any) has finished.
-
-#### Clearing and interupting
-
-Since each message added into the queue may take a bit of time to actually be announced, it's possible that the user has navigated elsewhere in the mean time, making the queued up messages not relevant.
-
-The announcer plugin allows you to clear the entire queue by calling `this.$announcer.clear()`. Additionally if you want to interup the messages being currently spoken, the announcer plugin offers the `this.$announcer.stop()`-method.
-
-#### Canceling individual messages
-
-In some cases you may not want to clear the entire queue, but instead cancel out a single message.
-
-Imagine an App with a row of tiles, it's possible that before the title of the role is being spoken out, the user already navigates through the tiles within the row. Traditionally you'd use the focus event to speak out info about each tile (i.e. adding tot the queue). You don't want all previously focused tiles to still be announced, but would still want the category of the row to be announced, making clearing the queue not required.
-
-The `speak()`-method return a Promise that also contains a `cancel()` function. When called, it will cancel that specific message and remove it from the queue before it can be spoken out.
-
-Additionally if you want to _interrupt_ a specific messages as it's being spoken out as well and go straight to the next message in the queue (i.e. the newly focused item, for example). You can use the `stop()` message that is returned on the Promise returned by the `speak()`-method.
-
-```js
-Blits.Component('MyTile', {
-  //
-  props: ['title'],
-  state() {
-    return {
-      message: null
-    }
-  },
-  hooks: {
-    focus() {
-      // add message to the announcement queue
-      this.message = this.$announcer.speak(`This is tile ${this.title}`)
-    },
-    unfocus() {
-      // when unfocused interrupt the message if it's already being spoken out
-      this.message.stop()
-      // and cancel the message to remove it from the queue
-      this.message.cancel()
-    }
-  }
-})
-```
-
-## Enabling / disabling the announcer
-
-By default the announcer is disabled. This means that whenever you call `this.$announcer.speak()` there will actually not be anything spoken out via the Text To Speech engine.
-
-In order to enable utterances being spoken out, you can set the Blits launch setting `announcer` to `true` in the index.js.
-
-Alternatively the announcer can be enabled or disabled run time by using one of the following methods on the Announcer pluging:
-
-- `this.$announcer.enable()` - activates the announcer
-- `this.$announcer.disable()` - deactivates the announcer
-- `this.$announcer.disable(true/false)` - turns the announcer or on off

package/docs/plugins/theme.md

@@ -1,176 +0,0 @@
-# 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 means 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/router/basics.md

@@ -1,175 +0,0 @@
-# Router Basics
-
-The Blits framework comes with a built-in, performant router that eliminates the need to pull in any additional dependencies into your App.
-
-Before we dive into the details, let's first touch base on some key concepts.
-
-## Key concepts
-
-### Pages are regular Blits Components
-
-The router in Blits is primarily used to navigate between Pages in your App. In the context of a Blits App, a Page is just a regular Blits Component. Usually it will be a Component that fills the entire screen. But it is also possible to have only a smaller portion of the screen contain dynamic routed content.
-
-### URL hash
-
-When navigating to a page, the hash in the URL of the browser will automatically be updated (i.e. `http://localhost:8080/#my/page`) to match the current page. The hash can also be used to _deep-link_ directly into your application. Upon first load, the router functionality will evaluate the URL hash and try to match that to a defined route. If a matching route is found, it will load that page as deep linked content.
-
-## Defining Routes
-
-Routes are defined in the main Application component, as an Array under the `routes` key of the configuration object.
-
-Each route in this array, is an Object literal that includes the following key properties:
-
-- `path` - the url hash to the route (i.e. `/my/page`)
-- `component` - the Blits component to render for the route. This can be a direct reference, but also a promise or a dynamic import that resolves to a Blits component
-- `hooks` (optional) - hooks such as `before` can be defined to execute code before navigating to the route
-- `options` (optional) - additional options defining route behaviour, such as `keepAlive` and `inHistory`
-- `transitions` (optional) - used to define custom transitions between pages
-
-### Dynamic routes with params
-
-Besides static routes such as `/account` and `/settings/wifi/advanced`, the Blits router also supports dynamic routes where URI parts can contain params.
-
-To define a param in a route path, prefix a string with a colon (`:`), followed by the name of the param, e.g. `/movies/:genre/:id`. This route path will match a URI hash such as `#/movies/sci-fi/65281918`. The router will take the params and inject them as a `prop` into the Page that's being navigated to.
-
-To access these props in the Page component, they must first be defined in the Page component as _props_ first (i.e. `props: ['genre', 'id']`). Once defined, the values (`sci-fi` and `65281918`) in this case, will be available on the `this` scope as `this.genre` and `this.id` (or as `$genre` and `$id` when used in the template), as with any regular Component.
-
-#### Using query parameters in routes
-
-According to the browser specifications, query parameters are not part of a URL hash. This means that query parameters should be placed _before_ the URL hash (i.e. `http://localhost:5173?id=100&name=john#/my/page/hash`) and implies that "real" query parameters are _not_ part of the route paths.
-
-In this case `id` and `name` won't automatically be made available as props inside a Blits component. They can however be retrieved using `document.location.search` in combination with `new URLSearchParams`, and can be used in an App's `index.js` to set dynamic launch settings for example.
-
-Sometimes you may actually want pass custom data into a Blits component, without it being part of the dynamic route path or `data`-object during navigation. For these cases Blits allows you to use query parameters as part of a route (i.e. `#/series/simpsons/5/10?id=100&name=john`).
-
-This URL hash will match the route `/series/:show/:season/:episode` and it will pass `id` and `name` as additional props into the Page component. Note: similar to dynamic path params, route query params should also be defined in the Page component as _props_ first (i.e. `props: ['id', 'name']`) in order to be accessed on the `this`-scope.
-
-## Router view
-
-The routes are loaded into a `<RouterView />` component, which acts as a placeholder for the routed Page components.
-
-The `<RouterView />` component can be positioned and sized as you would expect from a normal Blits Component.
-
-
-```js
-export default Blits.Application({
-  template: `
-    <Element>
-      <RouterView x="300" y="200" w="1520" h="680" />
-    </Element>
-  `,
-  routes: [
-      { path: '/', component: Home },
-      { path: '/details', component: () => import('./pages/Details.js'), },
-      { path: '/account',
-        component: () => {
-          // imagine this is an API call or some other async action
-          return new Promise((resolve) => {
-            resolve(Account)
-          })
-        }
-      }
-  ],
-  // ...
-})
-```
-
-## Navigation
-
-Each component in a routed Blits app has a `this.$router` object that provides access to the Router instance. It can be used to programmatically navigate to pages, by calling the `to()` method on it.
-
-The `this.$router.to()`-method accepts 3 arguments:
-
-- `path` - the path of the route to navigate to
-- `data` (optional) - an object with data to pass into the page as `props`
-- `options` (optional) - additional options defining route behaviour, such as `keepAlive` and `inHistory` (these will overwrite any options specified for a route in the routes array)
-
-```js
-export default Blits.Component('Poster', {
-  input: {
-    enter() {
-      this.$router.to('/movie/details', {id: '1', img: 'details.png'}, {inHistory: false})
-    }
-  }
-})
-```
-
-Whenever you navigate to a new page, the URL hash will automatically be updated. Unless specified otherwise, navigating to a new page, will add that route to the history stack. The `back` input action is automatically wired up to navigate back down the history stack.
-
-## Deeplinking
-
-The Router plugin has support for deeplinking. When the App is loaded with a URL hash (i.e. `#/pages/settings/network`), the router will try to match that hash to a defined route. This means that your app can be deep linked into, by simply providing the correct URL hash.
-
-This is an important feature for several reasons:
-
-- It will allow external sources (like operators and UIs) to link directly to a specific page in your app (i.e. the details page of a specific movie)
-- If dynamic routes are used, the App only loads what is needed, to keep memory usage low and the initial load time fast
-- Data provided in the URL hash can still be used to set the initial state of the App
-
-## Backtracking
-
-When a user enters your App via a deeplink, there is technically no history available. By default, this means that a Back keypress goes straight to
-the App's `root`-route (i.e. the `Blits.Application()`-component).
-
-In some cases, you may want walk back down the logical path of the deeplinked page instead, and navigate to the first existing parent route (i.e. go from `/movies/comedy/american-pie` to `/movies/comedy`).
-
-By setting the route option `backtrack` to `true` in the route definition (or in the `this.$router.to()`-method), the router will recursively remove the last part of the route hash, until it finds a valid path to navigate to.
-
-```js
-{
-  path: '/examples/router-hooks/episode/:id',
-  component: Episode,
-  transition: PageTransitions.slideInOutUp,
-  options: {
-    backtrack: true,
-  },
-},
-{
-  path: '/examples/router-hooks/episode',
-  component: EpisodesOverview,
-},
-```
-
-In the example above, the `backtrack` option is set to `true` for the `/examples/router-hooks/episode/:id` route. When the user navigates to `/examples/router-hooks/episode/1`, the `back` input action will navigate to `/examples/router-hooks/episode` instead of exiting the App.
-
-## Router API
-
-The Router API provides several useful methods and properties for managing routes and navigation:
-
-- `this.$router.to()` - navigating to a different location (as discussed above)
-- `this.$router.back()` - programmatically navigate back down the history stack
-- `this.$router.currentRoute` - retrieve the current route
-- `this.$router.routes` - retrieve the list of all routes
-- `this.$router.navigating` - retrieve the current navigating state
-- `this.$router.state` - reactive router state (see below)
-
-### Reactive router state
-
-The reactive router state (`this.$router.state`) can be useful in situations where you want to hook up reactive changes in your App to Route changes.
-
-The `state` variable on the `this.$router` object returns a reactive object with 2 keys: `path` and `navigating`. The values of these keys will automatically update when the router navigates from one page to another.
-
-The router state changes can be used in a Blits template, they can be _watched_ and they can be used in generic business logic, as demonstrated in the example below.
-
-```js
-export default Blits.Component('MyComponent', {
-  template: `
-    <Element w="1920" h="1080">
-      <!-- dynamically display the current path -->
-      <Text x="100" h="100" :content="$$router.state.path" />
-      <!-- show loading text when router is navigating -->
-      <Text :show="$showLoader">Loading ...</Text>
-    </Element>
-  `,
-  watch: {
-    '$router.state.path'(v, old) {
-      Log.info(`Router Path changed from ${old} to ${v}`)
-    }
-  },
-  computed: {
-    showLoader() {
-      return this.$router.state.navigating
-    }
-  }
-})
-```