@lightningjs/blits 1.30.1 → 1.31.0

package/docs/router/hooks.md

@@ -1,70 +0,0 @@
-# Router Hooks
-
-The Blits router supports hooks that allow you to execute code at specific points during the navigation process.
-
-Hooks are defined per route in the optional `hooks` key within the Route configuration object.
-
-> Currently, the Blits router only supports the before hook, with additional hooks planned for future releases.
-
-## Before hook
-
-The before hook is executed before the navigation occurs. It can be used for checks, such as verifying user authentication for a specific route, for pre-fetching data, or for executing logic like sending stats beacons.
-
-The before hook is defined as a function that receives 2 arguments: the Route object that is being navigated `to`. And the Route object that is being navigated away `from`.
-
-```js
-export default Blits.Application({
-  // ...
-  routes: [
-      {
-        path: '/',
-        component: Home,
-        hooks: {
-          before(to, from) {
-            // custom logic
-          }
-        }
-      }
-  ],
-  // ...
-})
-```
-
-The before hook can optionally return a value, which will influence the behaviour of the route change:
-
-- when  `false` is returned, the router will fail to finish the routing, and act as if _no matching route was found_
-- when a `string` is returned, the router will interpret this as a _new route path to redirect to_
-- when an `object` is returned, the router will interpret this as a route object, allowing to _modify (or completely replace) the route object_ being navigated to
-
-Returning an `object` is a simple, yet powerful, mechanism to add advanced runtime configuration to your routes. A common scenario is to overwrite certain parts of the route object provided in the `to`-argument, such as the route options (such as `inHistory` or `stayAlive`) or define conditional page transitions.
-
-It's also possible to add custom data to the route object in the `key` object. Custom data should be an object literal. When the new page loads, the keys in the `data` object are injected into the Component as `props`.
-
-```js
-export default Blits.Application({
-  // ...
-  routes: [
-      {
-        path: '/video/details/:id',
-        component: Details,
-        hooks: {
-          before(to, from) {
-            // redirect to an error page when id is not a number
-            if(isNaN(to.params.id)) {
-              return '/not-valid'
-            }
-            // set a different transition when navigating from home page
-            if(from && from.path === '/home') {
-              to.transition = slideInTransition
-            }
-            // add custom data
-            to.data.title = 'Hello World'
-            // finally return the modified route object
-            return to
-          }
-        }
-      }
-  ],
-  // ...
-})
-```

package/docs/router/transitions.md

@@ -1,146 +0,0 @@
-# Router Transitions
-
-Page transitions add a layer of visual polish to your application by animating the change between routes.
-
-When the router in Blits navigates to a new page, it automatically applies a subtle _fade-in / fade-out_ transition. Blits also allows to specify custom transitions on a per-route basis.
-
-## Defining Route Transitions
-
-In the Route object, the `transition` key can be used to specify which transition should be applied when navigating _to_ that route.
-
-It accepts a _Transition_ object, with 3 optional keys: `before`, `in`, `out`.
-
-### Before
-
-The `before` key is used to set a property to a certain value _before_ the page transition starts. The properties are set on the page that is being navigated _to_. For example, it can be used to position the page out of screen by setting the `x` value to a negative value, in order to create a _slide in from the right_ effect. Or the `alpha` property can be set to `0` if you want to create a _fade-in_ effect.
-
-```js
-const pageTransition = {
-  // position the new page outside the screen on the left side
-  before: {
-    prop: 'x',
-    value: -1920
-  }
-}
-```
-
-In order to set multiple properties to an initial state, an Array of objects can be assigned to the `before` key.
-
-```js
-const pageTransition = {
-  // position the new page outside the screen on the left side
-  // and set the alpha to 0
-  before: [{
-    prop: 'x',
-    value: -1920
-  },{
-    prop: 'alpha',
-    value: 0
-  }]
-}
-```
-
-### In
-
-The `in`-key is used to define how the new page should transition _into_ the screen, given the initial defaults, in combination with any properties set in the optional `before` key.
-
-The transition is defined by a _Transition_ object, consisting of:
-
-- `prop` - the property to apply the transition on
-- `value` - the value to transition to
-- `duration` (optional) - the duration of the transition in milliseconds (defaults to `300ms`)
-- `easing` (optional) - the easing function applied to the transition (defaults to `ease-in`)
-
-```js
-const pageTransition = {
-  // position the new page outside the screen on the left side
-  before: {
-    prop: 'x',
-    value: -1920
-  },
-  // transition the new page from outside, into the screen
-  in: {
-    prop: 'x',
-    value: 0,
-    duration: 800,
-    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
-  }
-}
-```
-
-In order to transition multiple properties, an Array of objects can be assigned to the `in` key.
-
-```js
-const pageTransition = {
-  // position the new page outside the screen on the left side
-  // and set the alpha to 0
-  before: [{
-    prop: 'x',
-    value: -1920
-  },{
-    prop: 'alpha',
-    value: 0
-  }],
-  // transition the new page from outside, into the screen
-  // and transition the alpha from 0 to 1
-  in: [{
-    prop: 'x',
-    value: 0,
-    duration: 800,
-    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
-  },{
-    prop: 'alpha',
-    value: 1,
-    duration: 500,
-  }]
-}
-```
-
-### Out
-
-Finally the `out`-key is used to define how the old page should transition _out of_ the screen.
-
-Similar to the `in`-transition, the `out`-transition is defined by a _Transition object_, consisting of:
-
-- `prop` - the property to apply the transition on
-- `value` - the value to transition to
-- `duration` (optional) - the duration of the transition in milliseconds (defaults to `300ms`)
-- `easing` (optional) - the easing function applied to the transition (defaults to `ease-in`)
-
-And in order to transition multiple properties at the same time during the _out_ transition, an Array of transition objects can be supplied.
-
-
-```js
-const pageTransition = {
-  // position the new page outside the screen on the left side
-  // and set the alpha to 0
-  before: [{
-    prop: 'x',
-    value: -1920
-  },{
-    prop: 'alpha',
-    value: 0
-  }],
-  // transition the new page from outside, into the screen
-  // and transition the alpha from 0 to 1
-  in: [{
-    prop: 'x',
-    value: 0,
-    duration: 800,
-    easing: 'cubic-bezier(0.20, 1.00, 0.80, 1.00)'
-  },{
-    prop: 'alpha',
-    value: 1,
-    duration: 500,
-  }],
-  // slide up the old page
-  // while rotating
-  out: [{
-    prop: 'y',
-    value: -1080
-  },{
-    prop: 'rotate',
-    value: 720
-  }]
-}
-```

package/docs/sidebar.json

@@ -1,171 +0,0 @@
-[
-  {
-    "text": "Getting Started",
-    "items": [
-      {
-        "text": "Intro",
-        "link": "/getting_started/intro"
-      },
-      {
-        "text": "Getting started",
-        "link": "/getting_started/getting_started"
-      },
-      {
-        "text": "File structure",
-        "link": "/getting_started/file_structure"
-      }
-    ]
-  },
-  {
-    "text": "Essentials",
-    "items": [
-      {
-        "text": "Application root",
-        "link": "/essentials/application_root"
-      },
-      {
-        "text": "Component basics",
-        "link": "/essentials/components"
-      },
-      {
-        "text": "Template syntax",
-        "link": "/essentials/template_syntax"
-      },
-      {
-        "text": "Supported element attributes",
-        "link": "/essentials/element_attributes"
-      },
-      {
-        "text": "Displaying images",
-        "link": "/essentials/displaying_images"
-      },
-      {
-        "text": "Displaying text",
-        "link": "/essentials/displaying_text"
-      },
-      {
-        "text": "Application settings",
-        "link": "/essentials/settings"
-      }
-    ]
-  },
-  {
-    "text": "Components",
-    "items": [
-      {
-        "text": "State",
-        "link": "/components/component_state"
-      },
-      {
-        "text": "Props",
-        "link": "/components/props"
-      },
-      {
-        "text": "Computed properties",
-        "link": "/components/computed_properties"
-      },
-      {
-        "text": "Watchers",
-        "link": "/components/watchers"
-      },
-      {
-        "text": "Hooking into lifecycle events",
-        "link": "/components/lifecycle_events"
-      },
-      {
-        "text": "Handling User input",
-        "link": "/components/user_input"
-      },
-      {
-        "text": "Methods",
-        "link": "/components/methods"
-      },
-      {
-        "text": "Utility methods",
-        "link": "/components/utility_methods"
-      }
-    ]
-  },
-  {
-    "text": "Transitions and Animations",
-    "items": [
-      {
-        "text": "Transitions",
-        "link": "/transitions_animations/transitions"
-      }
-    ]
-  },
-  {
-    "text": "Built-in components",
-    "items": [
-      {
-        "text": "Directives",
-        "link": "/built-in/directives"
-      },
-      {
-        "text": "For loop",
-        "link": "/built-in/for-loop"
-      },
-      {
-        "text": "Layout",
-        "link": "/built-in/layout.md"
-      }
-    ]
-  },
-  {
-    "text": "Performance",
-    "items": [
-      {
-        "text": "Lazy Loading",
-        "link": "/performance/lazy-loading"
-      }
-    ]
-  },
-  {
-    "text": "Router",
-    "items": [
-      {
-        "text": "Basics",
-        "link": "/router/basics"
-      },
-      {
-        "text": "Hooks",
-        "link": "/router/hooks"
-      },
-      {
-        "text": "Transitions",
-        "link": "/router/transitions"
-      }
-    ]
-  },
-  {
-    "text": "Plugins",
-    "items": [
-      {
-        "text": "Text-to-Speech / Announcer",
-        "link": "/plugins/text-to-speech-announcer"
-      },
-      {
-        "text": "Language",
-        "link": "/plugins/language"
-      },
-      {
-        "text": "Theme",
-        "link": "/plugins/theme"
-      },
-      {
-        "text": "Global App State",
-        "link": "/plugins/global_app_state"
-      }
-    ]
-  },
-  {
-    "text": "Performance",
-    "items": [
-      {
-        "text": "Lazy loading",
-        "link": "/performance/lazy-loading"
-      }
-    ]
-  }
-]

package/docs/transitions_animations/transitions.md

@@ -1,150 +0,0 @@
-# Transitions
-
-So far we have explored how to create components and draw elements on the screen. But everything has
-been rather static so far.
-
-We did learn how to _reactively_ change values and trigger rerenders based on that. So if you try the example below, you'll see that indeed our golden element changes position. But it just jumps from one place to another:
-
-```js
-export default Blits.Component('Gold', {
-  template: `
-    <Element color="gold" w="100" h="100" :x="$x" :y="$y" />
-  `,
-  state() {
-    return {
-      x: 0,
-      y: 0,
-    }
-  },
-  input: {
-    enter() {
-      this.x = this.x + 100
-      this.y = this.y + 50
-    }
-  },
-```
-
-Using _transitions_ we really make our App come alive.
-
-## Applying a transition
-
-Blits offers an easy and intuitive way to apply transitions. All you need to do is add the `.transition` modifier to a reactive attribute, and now whenever you change the value referenced in the attribute, it will automatically _smooth_ into the new value.
-
-```js
-export default Blits.Component('Gold', {
-  template: `
-    <Element color="gold" w="100" h="100" :x.transition="$x" :y.transition="$y" />
-  `,
-  state() {
-    return {
-      x: 0,
-      y: 0,
-    }
-  },
-  input: {
-    enter() {
-      this.x = this.x + 100
-      this.y = this.y + 50
-    }
-  },
-```
-
-If we try out the modified example above, you'll notice how much difference adding a simple transition makes.
-
-When the `.transition`-modifier is added to a reactive attribute, a default `ease-in` transition with a duration of `300ms` is applied
-
-## Customizing transitions
-
-While the default transition will look pretty good out of the box and is great for quickly improving the look of your App, you may want to customize specific transitions.
-
-Blits gives you full control over your transitions, with a simple to use format, right inside your template.
-
-Instead of referencing your component's state variable directly, you can also supply an inline `object literal`` in the attribute with a `.transition`-modifier. This will allow you to pass a number of options to change the way the transition will work.
-
-The transition object must have a `value` key, which references the state variable (or prop or computed property) that triggers the transition.
-
-Furthermore, you can specify:
-
-- `duration` - the duration of the transition in `ms`
-- `delay` - the time in `ms` after which the transition should initiate
-- `easing` - the easing function of the transition. Can be one of the default easing options listed below, or a custom `cubic-bezier` definition (i.e. `cubic-bezier(0,1.35,.99,-0.07)`).
-
-```xml
-<Element color="gold" w="100" h="100"
-  :x.transition="{value: $x, duration: 300, easing: 'ease-in-back', delay: 400}"
-  :y.transition="{value: $x, duration: 300, easing: 'cubic-bezier(1,-0.64,0.39,1.44)'}">
-</Element>
-```
-
-Besides a reference to the `value`, you can also use dynamic values for the other keys in the transition object. This way you'll be able to dynamically control the delay, duration or easing function.
-
-```xml
-<Element color="gold" w="100" h="100"
-  :x.transition="{value: $x, duration: $dynamicDuration, delay: $dynamicDelay}">
-</Element>
-```
-
-### Available easing functions
-
-- `ease-in`
-- `ease-out`
-- `ease-in-out`
-- `ease-in-sine`
-- `ease-out-sine`
-- `ease-in-out-sine`
-- `ease-in-cubic`
-- `ease-out-cubic`
-- `ease-in-out-cubic`
-- `ease-in-circ`
-- `ease-out-circ`
-- `ease-in-out-circ`
-- `ease-in-back`
-- `ease-out-back`
-- `ease-in-out-back`
-
-## Listening to transition events
-
-Sometimes you may want to perform an action when a transition _ends_ or when it _starts_.
-
-You can easily hook into these transition events by adding a `start` and `end` key to the transition object. Both values should be a function (or a reference to a `method` on your component).
-
-The `start` function will be called when the transition actually starts (after a possible specified delay) and the `end` function is called as soon as the transition is finished.
-
-```js
-export default Blits.Component('Gold', {
-  template: `
-    <Element color="gold" w="100" h="100"
-      :x.transition="{value: $x, start: $transitionBegin, end: $transitionEnd}"
-    />
-  `,
-  ///
-  methods: {
-    transitionBegin() {
-      //
-    },
-    transitionEnd() {
-      //
-    },
-  }
-```
-
-It is also possible to keep track of the entire progress of a transition. Every frametick during a transition (ideally once every 16ms), the renderer reports the progress of the transition. You can hook into this event by specifying a `progress` key on the transition configuration object, with a function to excute.
-
-This function is executed _every_ frametick, and receives the current progress and the previous progress as its arguments. The progress is indicated as a value between `0` and `1`, where 0 means start and 1 means finished.
-
-```js
-export default Blits.Component('Gold', {
-  template: `
-    <Element color="gold" w="100" h="100"
-      :x.transition="{value: $x, progress: $transitionProgress}"
-    />
-  `,
-  ///
-  methods: {
-    transitionProgress(progress, previousProgress) {
-      if(progress >= 0.5 && previousProgress < 0.5) {
-        // halfway through the transition
-      }
-    },
-  }
-```

package/jsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "allowJs": true,
-    "checkJs": true,
-    "moduleResolution": "node",
-    "baseUrl": "./"
-  },
-  "include": ["src"],
-  "exclude": ["node_modules"]
-}