@lightningjs/blits 0.8.1 → 0.9.0

package/docs/transitions_animations/transitions.md

@@ -0,0 +1,132 @@
+# Blits - Lightning 3 App Development Framework
+
+## 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_ changes 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('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('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100" :x.transiton="$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 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 inlien `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.
+
+Further more 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 defaults easing options listed below, or a custom `cubic-bezier` definitions (i.e. `cubic-bezier(0,1.35,.99,-0.07)`).
+
+```xml
+<Element color="gold" w="100" h="100"
+  :x.transiton="{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.transiton="{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 transiti)on events by adding a `start` and `end` key to the transition object. Both value 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 transitions is finished.
+
+```js
+export default Blits('Gold', {
+  template: `
+    <Element color="gold" w="100" h="100"
+      :x.transiton="{value: $x, start: $transitionBegin, end: $transitionEnd}"
+    />
+  `,
+  ///
+  methods: {
+    transitionBegin() {
+      //
+    },
+    transitionEnd() {
+      //
+    },
+  }
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightningjs/blits",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {

package/src/component.js

@@ -40,6 +40,8 @@ import lifecycle from './lib/lifecycle.js'
 import Settings from './settings.js'
 import symbols from './lib/symbols.js'
 
+let counter = 0
+
 const stage = {
   element,
 }
@@ -56,10 +58,12 @@ const Component = (name = required('name'), config = required('config')) => {
       config.code = codegenerator.call(config, parser(config.template, name, parentComponent))
     }
 
+    component[symbols.identifier] = ++counter
+
     setupBase(component, name)
 
     // setup hooks
-    registerHooks(config.hooks, name)
+    registerHooks(config.hooks, component[symbols.identifier])
 
     // setup props
     // if (config.props) // because of the default props like id - might change this
@@ -97,7 +101,9 @@ const Component = (name = required('name'), config = required('config')) => {
       setupComponent(parentComponent)
     }
     if (config.hooks && config.hooks.frameTick) {
-      renderer.on('frameTick', (r, data) => emit('frameTick', name, this, [data]))
+      renderer.on('frameTick', (r, data) =>
+        emit('frameTick', component[symbols.identifier], this, [data])
+      )
     }
 
     this.parent = parentComponent
@@ -137,7 +143,10 @@ const Component = (name = required('name'), config = required('config')) => {
     })
 
     Object.defineProperty(this, symbols.originalState, {
-      value: (config.state && typeof config.state === 'function' && config.state.apply(this)) || {},
+      value: {
+        ...((config.state && typeof config.state === 'function' && config.state.apply(this)) || {}),
+        ...{ hasFocus: false },
+      },
       writable: false,
       enumerable: false,
       configurable: false,

package/src/fontLoader.js

@@ -1,26 +1,25 @@
-import { CoreExtension, WebTrFontFace, SdfTrFontFace } from '@lightningjs/renderer/core'
+import { WebTrFontFace, SdfTrFontFace } from '@lightningjs/renderer/core'
 
 import Settings from './settings'
+import { renderer } from './launch'
 
-export default class FontLoader extends CoreExtension {
-  async run(stage) {
-    Settings.get('fonts', []).forEach((font) => {
-      if (font.type === 'sdf' || font.type === 'msdf') {
-        // automatically map png key to file name
-        if (!font.png && font.file) {
-          font.png = font.file.replace(/\.[^.]+$/, `.${font.type}.png`)
-        }
-        // automatically map json to file name
-        if (!font.json && font.file) {
-          font.json = font.file.replace(/\.[^.]+$/, `.${font.type}.json`)
-        }
-
-        stage.fontManager.addFontFace(
-          new SdfTrFontFace(font.family, {}, font.type, stage, font.png, font.json)
-        )
-      } else if (font.type === 'web') {
-        stage.fontManager.addFontFace(new WebTrFontFace(font.family, {}, font.file))
+export default () => {
+  const stage = renderer.driver.stage
+  Settings.get('fonts', []).forEach((font) => {
+    if (font.type === 'sdf' || font.type === 'msdf') {
+      // automatically map png key to file name
+      if (!font.png && font.file) {
+        font.png = font.file.replace(/\.[^.]+$/, `.${font.type}.png`)
+      }
+      // automatically map json to file name
+      if (!font.json && font.file) {
+        font.json = font.file.replace(/\.[^.]+$/, `.${font.type}.json`)
       }
-    })
-  }
+      stage.fontManager.addFontFace(
+        new SdfTrFontFace(font.family, {}, font.type, stage, font.png, font.json)
+      )
+    } else if (font.type === 'web') {
+      stage.fontManager.addFontFace(new WebTrFontFace(font.family, {}, font.file))
+    }
+  })
 }

package/src/launch.d.ts

@@ -16,7 +16,7 @@
  */
 
 import ApplicationInstance from './application'
-
+import {type Stage} from '@lightningjs/renderer'
 interface WebFont {
   /**
   * Name of the font family
@@ -70,6 +70,9 @@ export type DebugLevel = 0 | 1 | 2
 export type LogTypes = 'info' | 'warn' | 'error' | 'debug'
 export type ReactivityModes = 'Proxy' | 'defineProperty'
 
+interface ExtensionLoader {
+  async (stage: Stage): void
+}
 /**
  * Settings
  *
@@ -92,11 +95,7 @@ export interface Settings {
   /**
    * Debug level for console log messages
    */
-  debugLevel?: DebugLevel | LogTypes[]
-  /**
-   * Font loader file
-   */
-  fontLoader?: any
+  debugLevel?: DebugLevel | LogTypes[],
   /**
    * Fonts to be used in the Application
    */

package/src/launch.js

@@ -21,6 +21,7 @@ import Settings from './settings.js'
 import { initLog, Log } from './lib/log.js'
 import { screenResolutions } from './lib/utils.js'
 import colors from './lib/colors/colors.js'
+import fontLoader from './fontLoader.js'
 
 export let renderer
 
@@ -36,11 +37,20 @@ export default (App, target, settings) => {
   //     })
   //   : new MainCoreDriver()
 
+  if ('fontLoader' in settings) {
+    Log.warn(
+      `
+
+Starting version 0.9.0 of Blits, the Launch setting \`fontLoader\` is not supported / required anymore.
+You can remove the option from your \`src/index.js\`-file. And you can safely remove the file \`src/fontLoader.js\` from your project.
+      `
+    )
+  }
+
   renderer = new RendererMain(
     {
       appWidth: settings.w || 1920,
       appHeight: settings.h || 1080,
-      coreExtensionModule: settings.fontLoader,
       fpsUpdateInterval: settings.fpsInterval || 1000,
       deviceLogicalPixelRatio:
         settings.pixelRatio ||
@@ -68,5 +78,5 @@ export default (App, target, settings) => {
     }
   }
 
-  renderer.init().then(() => initApp())
+  renderer.init().then(fontLoader).then(initApp)
 }

package/src/lib/codegenerator/generator.js

@@ -223,7 +223,7 @@ const generateForLoopCode = function (templateObject, parent) {
       parent = ${parent}
       if(!component.key) keys.length = 0
       const scope = Object.assign(component, {
-        key: Math.random(),
+        key: Math.random().toString(),
         ${index}: __index,
         ${item}: collection[__index],
     `)
@@ -241,7 +241,7 @@ const generateForLoopCode = function (templateObject, parent) {
 
   if ('key' in templateObject) {
     ctx.renderCode.push(`
-      keys.push(${interpolate(templateObject.key, 'scope.')})
+      keys.push(${interpolate(templateObject.key, 'scope.')}.toString())
     `)
   } else {
     ctx.renderCode.push(`

package/src/lib/hooks.js

@@ -19,20 +19,20 @@ import symbols from './symbols.js'
 
 const cbs = {}
 
-export const emit = (hook, name, scope, data = []) => {
-  cbs[name] && cbs[name][hook] && cbs[name][hook].apply(scope, data)
+export const emit = (hook, identifier, scope, data = []) => {
+  cbs[identifier] && cbs[identifier][hook] && cbs[identifier][hook].apply(scope, data)
 }
 
-export const privateEmit = (hook, name, scope) => {
+export const privateEmit = (hook, identifier, scope) => {
   const symHook = symbols[hook]
-  cbs[name] && cbs[name][symHook] && cbs[name][symHook].apply(scope)
+  cbs[identifier] && cbs[identifier][symHook] && cbs[identifier][symHook].apply(scope)
 }
 
-export const registerHooks = (hooks = {}, name) => {
-  cbs[name] = {}
+export const registerHooks = (hooks = {}, identifier) => {
+  cbs[identifier] = {}
   // Combines enumerable keys and symbol properties of the 'hooks' object
   const hookKeys = [...Object.keys(hooks), ...Object.getOwnPropertySymbols(hooks)]
   hookKeys.forEach((hook) => {
-    if (typeof hooks[hook] === 'function') cbs[name][hook] = hooks[hook]
+    if (typeof hooks[hook] === 'function') cbs[identifier][hook] = hooks[hook]
   })
 }

package/src/lib/lifecycle.js

@@ -17,6 +17,7 @@
 
 import { Log } from './log.js'
 import { emit, privateEmit } from './hooks.js'
+import symbols from './symbols.js'
 
 const states = ['init', 'ready', 'focus', 'unfocus', 'destroy']
 
@@ -34,9 +35,9 @@ export default {
       this.previous = this.current
       this.current = v
       // emit 'private' hook
-      privateEmit(v, this.component.name, this.component)
+      privateEmit(v, this.component[symbols.identifier], this.component)
       // emit 'public' hook
-      emit(v, this.component.name, this.component)
+      emit(v, this.component[symbols.identifier], this.component)
     }
   },
 }

package/src/lib/setup/base.js

@@ -35,7 +35,7 @@ const shaderAlias = {
   rounded: 'radius',
 }
 
-export default (component, name) => {
+export default (component, name, identifier) => {
   Object.defineProperties(component.prototype, {
     name: {
       value: name,
@@ -43,8 +43,15 @@ export default (component, name) => {
       enumerable: true,
       configurable: false,
     },
+    [symbols.identifier]: {
+      value: component[symbols.identifier],
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    },
     focus: {
       value: function (e) {
+        this[symbols.state].hasFocus = true
         Focus.set(this, e)
       },
       writable: false,
@@ -53,6 +60,7 @@ export default (component, name) => {
     },
     unfocus: {
       value: function () {
+        this[symbols.state].hasFocus = false
         this.lifecycle.state = 'unfocus'
       },
       writable: false,

package/src/lib/setup/state.js

@@ -22,7 +22,7 @@ import symbols from '../symbols.js'
 export default (component, state) => {
   component[symbols.stateKeys] = []
 
-  state = state.apply(component.prototype)
+  state = { ...state.apply(component.prototype), ...{ hasFocus: false } }
   Object.keys(state).forEach((key) => {
     if (component[symbols.propKeys] && component[symbols.propKeys].indexOf(key) > -1) {
       Log.error(`State ${key} already exists as a prop`)

package/src/lib/symbols.js

@@ -3,6 +3,8 @@ export default {
   cursorTagStart: Symbol('cursorTagStart'),
   computedKeys: Symbol('computedKeys'),
   destroy: Symbol('destroy'),
+  id: Symbol('id'),
+  identifier: Symbol('identifier'),
   index: Symbol('index'),
   init: Symbol('init'),
   inputEvents: Symbol('inputEvents'),

package/boilerplate/js/default/src/fontloader.js

@@ -1,4 +0,0 @@
-// temporary workaround for Vite importChunkUrl plugin
-// @ts-ignore
-import FontLoader from '@lightningjs/blits/fontloader'
-export default FontLoader

package/docs/computed_properties.md

@@ -1,18 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-## Computed properties
-
-So far we've learned how to utilize internal state variables and props passed by a parent in (the template of) our component.
-We can even perform simple operations like `Math.max()` or `str.toUpperCase()` directly within an argument of the template.
-
-However, sometimes it's more clear and more maintainable to abstract these operations into what we call _computed properties_.
-
-Within the computed key of the Component configuration object, you can specify a set of functions. Each function name you define (`offset()` for example) becomes accessible as a computed property.
-
-In your template, you can reference these computed properties by prefixing them with a dollar sign (e.g., `$offset`). In the rest of your app's code, you can access these computed properties (but not modify them) using `this.offset`.
-
-Within a computed property, you can reference one or more state variables or props and return a value based on calculations or logical operations.
-
-Whenever the value of any referenced variable changes, the computed property will automatically recalculate. If a computed property is referenced reactively in the template (i.e., prefixed with colons `:`), it will also trigger an automatic rerender of that portion of the template.
-
-Computed properties are a powerful tool for enhancing the readability of your component code. By abstracting complex or frequently used calculations into computed properties, you can make your code (and especially your template) more concise and easier to understand.

package/docs/getting_started.md

@@ -1,40 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-## Getting Started
-
-To begin with Blits, follow these simple steps to set up your development environment and create your first Lightning 3 App.
-
-### Installation
-
-1. Open your terminal or command prompt.
-
-2. Run the following command to start a new Blits Lightning 3 App project:
-
-```bash
-npx @lightningjs/blits@latest
-```
-
- You will be guide through a few short questions, to generate a new project with all the boilerplate code you need to start building your own Lightning 3 App.
-
-3. Navigate to the newly created project directory and install the project dependencies:
-
-```bash
-cd my_blits_app
-npm install
-```
-
-### Running Your App
-
-4. After installing the dependencies, you can start your development server by running:
-
-```bash
-npm run dev
-```
-
-This command will create an application bundle and launch a development server using Vite.
-
-2. Once the server is up and running, open your web browser and navigate to the URL displayed in the console. Congratulations! You now have your brand new Blits Lightning 3 App up and running.
-
-### Next steps
-
-You are now ready to dive into the world of App development using Blits. In the following sections, we will explore the core concepts and guide you through building your TV applications step by step.

package/docs/props.md

@@ -1,46 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-## Props
-
-Components in Blits have their own internal state and logic. However, as each component is part of the larger app's 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.
-
-In the Component configuration object, you can specify exactly which props a component can accept. These props are passed to the child component via attributes in the parent component's template. Any attributes 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 list their names within the `props` array.
-
-```javascript
-{
-  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 your component's state (i.e. `<Element color="$color" />`). Likewise, you can access a prop inside a component's code (e.g., inside the `ready()` lifecycle hook) using `this.color` (note: without a dollar sign!).
-
-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 can either reference the prop inside the component state (using `this.myprop`) or use the prop in a `computed` property.
-
-For more advanced usage, you can define props using an array of objects for each prop. 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.
-
-```js
-export default Blits.Component('MyComponent', {
-  // ...
-  props: [
-    'color',
-    {
-      key: 'alpha',
-      default: 0.5,
-      required: true,
-      validate(v) {
-        return v <= 1 && v >= 0;
-      },
-      cast: Number
-    }
-  ]
-})
-```
-
-You can mix and match the simple string notation with the more advanced object notation within the same `props` array.

package/docs/template_syntax.md

@@ -1,65 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-## Template structure
-
-Blits uses an easy-to-read _XML-style_ template syntax. The syntax is inspired by frameworks like VueJS, so developers familiar with Vue will recognize certain concepts.
-
-The _template_ key in the Componentn configuration object holds a string with an XML-like structure. Templates often span multiple lines, so it's advisable to use a JS template literal.
-
-You can use different tags in your templates. And similar to HTML you can use arguments and nested tags. Self-closing tags and HTML-style comments are also supported.
-
-The default tag within a template is the `<Element>` tag, which corresponds to a node in the Lightning 3 renderer. For each element, you can define a set of predefined render properties, such as `x`, `y`, `w`, `color`, and more. Detailed information regarding the attributes supported by the `<Element>` tag can be found [here](./element_attributes.md).
-
-Consider the following template example:
-
-```xml
-<Element x="20" y="20">
-  <Element w="100" h="100" x="360" color="#0891b2" />
-  <Element w="$width" h="$height" color="$color" />
-  <Element :w="$changingWidth" :h="Math.floor($height / 5)" :color="$highlight" />
-</Element>
-```
-
-### Hardcoded arguments
-
-In this template, you'll observe certain arguments with hardcoded values. You use these to configure the parts of your component that never change.
-
-### Dynamic arguments
-
-Additionally, some arguments contain a value prefixed with a dollar sign (`$`), representing _dynamic_ arguments. When the component renders, it automatically populates these dynamic values based on the component's state (or props or computed properties).
-
-### Reactive arguments
-
-Furthermore, certain arguments are prefixed with a colon sign (`:`), indicating _reactive_ arguments. These are not only dynamically set when your component renders, but also _rerender_ the corresponding part of the template whenever the referenced value in your component's internal state changes. This reactive data binding eliminates the need for manual template patching, as seen in Lightning 2.
-
-Reactive arguments support _interpolation_, enabling the use of simple JavaScript instructions, such as ternary conditions or basic string and Math manipulations. For more complex logic, it's recommended to abstract this into a Component method or a Computed property.
-
-## Custom components
-
-As your component grows in complexity, you may want to reorganize your codebase with custom components, abstracting and reusing both templates and logic.
-
-Inside a component template, you can utilize sub-components (i.e. a `Menu` component) and reference them with tags like `<Menu></Menu>`.
-
-In order for the `<Menu />` tag to become available for use in a component's template, you first have to `import` the file that exports that component.
-
-Next you have to _register_ this imported component using the `components`-key in the configuration object. The `components` key is an _object literal_, where the value is the reference to the Blits component. The key will correspond with the _tag_ that can be used to invoke the component.
-
-```js
-
-import Menu from './components/menu.js'
-import Button from './components/button.js'
-
-export default Blits.Component('MyComponent', {
-  components: {
-    Menu, // makes <Menu /> available for use in the template
-    MyButton: Button, // makes Button available as <MyButton /> in the template
-  },
-  template: `
-    <Element>
-      <Menu />
-      <MyButton />
-    </Element>
-  `
-})
-
-```

package/docs/watchers.md

@@ -1,38 +0,0 @@
-# Blits - Lightning 3 App Development Framework
-
-## Watching for Changes
-
-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, as side effects could potentially lead your app into an endless loop if not handled carefully.
-
-Instead, Blits allows you to specify **watchers**.
-
-### 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 to the name of the internal state variable, prop, or computed property that you want to watch. Whenever the target value 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.
-
-### Example:
-
-```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 'alpha' value changes, the watcher function associated with 'alpha' will be invoked. The function checks if the new value is greater than the old value and executes custom logic accordingly.