@lightningjs/blits 0.8.1 → 0.9.1

package/src/lib/reactivity/reactive.js

@@ -15,76 +15,89 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { track, trigger } from './effect.js'
-
-const arrayMethods = [
-  'constructor',
-  'includes',
-  'indexOf',
-  'lastIndexOf',
-  'push',
-  'pop',
-  'shift',
-  'splice',
-  'unshift',
-  'sort',
-  'reverse',
-]
-
-const arrayPatchMethods = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse']
+import { track, trigger, pauseTracking, resumeTracking } from './effect.js'
+import symbols from '../symbols.js'
+
+const arrayPatchMethods = ['push', 'pop', 'shift', 'unshift', 'splice']
 
 const proxyMap = new WeakMap()
 
-const reactiveProxy = (target) => {
-  const isProxy = proxyMap.get(target)
-  if (isProxy) {
-    return isProxy
+const getProxy = (obj) => {
+  return proxyMap.get(obj)
+}
+
+const getRaw = (value) => {
+  const raw = value && value[symbols.raw]
+  return raw ? getRaw(raw) : value
+}
+
+const reactiveProxy = (original, _parent = null, _key) => {
+  // if original object is already a proxy, don't create a new one but return the existing one instead
+  const existingProxy = getProxy(original)
+  if (existingProxy) {
+    return existingProxy
   }
 
   const handler = {
     get(target, key, receiver) {
-      if (Array.isArray(target) && arrayMethods.includes(key)) {
-        return Reflect.get(target, key, receiver)
+      // return the original object instead of the proxied
+      if (key === symbols.raw) {
+        return original
       }
 
-      if (target[key] !== null && typeof target[key] === 'object') {
-        return reactiveProxy(target[key])
+      // handling arrays
+      if (Array.isArray(target)) {
+        // augment array path methods (that change the length of the array)
+        if (arrayPatchMethods.indexOf(key) > -1) {
+          return function (...args) {
+            pauseTracking()
+            const result = target[key].apply(this, args)
+            // trigger a change on the parent object and the key
+            // i.e. when pushing a new item to `obj.data`, _parent will equal `obj`
+            // and _key will equal `data`
+            trigger(_parent, _key)
+            resumeTracking()
+            return result
+          }
+        } else {
+          return Reflect.get(target, key, receiver)
+        }
       }
 
+      // handling objects (but not null values, which have object type in JS)
+      if (typeof target[key] === 'object' && target[key] !== null) {
+        if (Array.isArray(target[key])) {
+          track(target, key)
+        }
+        // create a new reactive proxy
+        return reactiveProxy(target[key], target, key)
+      }
+
+      // handling all other types
+      // track the key on the target
       track(target, key)
+      // return the reflected value
       return Reflect.get(target, key, receiver)
     },
     set(target, key, value, receiver) {
-      const oldValue = target[key]
+      // get the raw values (without proxy wrapper) so we can compare them
+      const oldRawValue = getRaw(target[key])
+      const rawValue = getRaw(value)
 
-      let result
-      if (typeof value === 'object' && Array.isArray(value) && proxyMap.get(target[key])) {
-        if (oldValue !== value) {
-          result = oldValue.splice(0, target[key].length, ...value)
-        } else {
-          result = true
-        }
-      } else {
+      let result = true
+      if (oldRawValue !== rawValue) {
         result = Reflect.set(target, key, value, receiver)
       }
 
-      if (typeof value === 'object') {
-        reactiveProxy(target[key])
-      }
-
-      if (key === 'length') {
-        trigger(target, key)
-      } else {
-        if (result && oldValue !== value) {
-          trigger(target, key)
-        }
+      if (result && oldRawValue !== value) {
+        trigger(target, key, true)
       }
       return result
     },
   }
 
-  const proxy = new Proxy(target, handler)
-  proxyMap.set(target, proxy)
+  const proxy = new Proxy(original, handler)
+  proxyMap.set(original, proxy)
   return proxy
 }
 

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,
@@ -262,15 +270,15 @@ export default (component, name) => {
 }
 
 const deleteChildren = function (children) {
-  // for (let i = 0; i < children.length; i++) {
-  //   if (!children[i]) return
-  //   if (Array.isArray(children[i])) {
-  //     deleteChildren(children[i])
-  //   } else if (children[i].destroy) {
-  //     children[i].destroy()
-  //   }
-  //   children[i] = null
-  // }
+  for (let i = 0; i < children.length; i++) {
+    if (!children[i]) return
+    if (Array.isArray(children[i])) {
+      deleteChildren(children[i])
+    } else if (children[i].destroy) {
+      children[i].destroy()
+    }
+    children[i] = null
+  }
 
   children.length = 0
 }

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'),
@@ -11,6 +13,7 @@ export default {
   methodKeys: Symbol('methodKeys'),
   originalState: Symbol('originalState'),
   propKeys: Symbol('propKeys'),
+  raw: Symbol('raw'),
   ready: Symbol('ready'),
   renderer: Symbol('renderer'),
   routes: Symbol('routes'),

package/src/router/router.js

@@ -236,12 +236,12 @@ const removeView = async (route, view, transition) => {
     cacheMap.set(route, { view: view, focus: previousFocus })
   } else {
     // remove and cleanup
-    // for (let i = 0; i < view[symbols.children].length; i++) {
-    //   if (view[symbols.children][i] && view[symbols.children][i].destroy) {
-    //     view[symbols.children][i].destroy()
-    //     view[symbols.children][i] = null
-    //   }
-    // }
+    for (let i = 0; i < view[symbols.children].length; i++) {
+      // if (view[symbols.children][i] && view[symbols.children][i].destroy) {
+      //   view[symbols.children][i].destroy()
+      view[symbols.children][i] = null
+      // }
+    }
     view.destroy()
     view = null
   }

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.