@lightningjs/blits 0.3.0

package/docs/components.md

@@ -0,0 +1,27 @@
+# Blits - Lightning 3 App Development Framework
+
+## Building Your First Component
+
+Components in Blits follow a clearly defined structure, which helps keep your code clean and guides you to quickly build your components.
+
+This universal structure is also valuable for the interoperability of components.
+
+
+### Creating a new Component
+
+Let's see how to create a new component and explore the basic anatomy of a component.
+
+A new component is created using the `Blits.Component()` function. This function accepts two arguments:
+
+1. The first argument is the name of the component, which is mainly used for debugging purposes. It's essential to choose a unique and descriptive name for your component, such as `Homepage`, `Loader` or `SidebarMenuItem`.
+
+2. The second argument is a configuration object, represented as an `object literal`. This configuration object can contain a predefined set of key-value pairs, including for example:
+
+   - `template`: to define the template for the component.
+   - `state`: to specify the component instance's internal state.
+   - `prop`: to define the props that can be passed into the component.
+   - `hooks`: allowing you to hook into different lifecycle events of the component.
+   - `input`: used to tap into user input.
+
+In the next sections, we will go into the details of each of the component configuration options.
+

package/docs/computed_properties.md

@@ -0,0 +1,18 @@
+# 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

@@ -0,0 +1,40 @@
+# 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 create a new Lightning 3 App project:
+
+```bash
+npx @lightningjs/blits@latest my_lightning3_app
+```
+
+This will generate the necessary boilerplate code in the folder `my_lightning3_app` for you to start building your own Lightning 3 App.
+
+3. Navigate to the newly created project directory and install the project dependencies:
+
+```bash
+cd my_lightning3_app
+npm install
+```
+
+### Running Your App
+
+1. 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 Lightning 3 App up and running.
+
+### Next steps
+
+You are now ready to dive into the world of TV 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/index.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Blits Lightning App Development Framework</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <!--link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"-->
+  <link
+    rel="stylesheet"
+    href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
+    title="docsify-darklight-theme"
+    type="text/css"
+/>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Blits <br />L3 App Development Framework',
+      repo: 'https://github.com/lightning-js/blits/',
+      loadSidebar: true,
+      relativePath: true,
+      auto2top: true,
+      search: {
+        maxAge: 24*60*60*1000, // one day
+        paths: 'auto',
+        placeholder: 'Type to search',
+        noData: 'No Results!',
+        depth: 6,
+      },
+      darklightTheme: {
+        defaultTheme : 'dark',
+      }
+    }
+
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
+  <script
+    src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
+    type="text/javascript">
+</script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
+</body>
+</html>

package/docs/lifecycle_events.md

@@ -0,0 +1,46 @@
+# Blits - Lightning 3 App Development Framework
+
+## Hooking into Lifecycle Events
+
+In Blits, components follow a defined flow of lifecycle events. Developers can integrate their logic into these events by specifying them in the `hooks` key of the Component configuration object.
+
+For each available lifecycle event, you can define a function with the same name as the event itself. This function will execute each time the event is triggered for your component's instance. It's essential to use a regular function instead of an arrow function if you intend to access the `this` scope of your component instance.
+
+### Lifecycle Events
+
+- **init()**: This event fires when the component is instantiated, just before it sends its render instructions to the Lightning renderer. At this point, the elements of your template won't be available yet.
+
+- **ready()**: The `ready` event fires when the component instance is fully initialized and rendered, indicating that it's ready for interaction.
+
+- **focus()**: This event triggers whenever the component instance receives focus. It's important to note that this event can fire multiple times during the component's lifecycle, depending on user interactions.
+
+- **unfocus()**: The `unfocus` event fires whenever the component instance loses focus. Similar to the `focus` event, it can occur multiple times during the component's lifecycle.
+
+- **destroy()**: The `destroy` event fires when the component is being destroyed and removed. This event provides an opportunity to perform any custom cleanup operations before the component is removed.
+
+### Example
+
+```javascript
+{
+  // Other component configurations...
+  hooks: {
+    init() {
+      // Logic to execute on init event
+    },
+    ready() {
+      // Logic to execute on ready event
+    },
+    focus() {
+      // Logic to execute on focus event
+    },
+    unfocus() {
+      // Logic to execute on unfocus event
+    },
+    destroy() {
+      // Logic to execute on destroy event
+    },
+  },
+};
+```
+
+In the provided example, each function within the `hooks` object corresponds to a specific lifecycle event, allowing developers to inject custom logic at different stages of the component's lifecycle.

package/docs/props.md

@@ -0,0 +1,44 @@
+# 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.
+
+```javascript
+{
+  props: [
+    {
+      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

@@ -0,0 +1,31 @@
+# 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 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 properties supported by the <Element> tag can be found here.
+
+As your component grows in complexity, you may want to organize your template with custom components, abstracting 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>`.
+
+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>
+```
+
+In this template, you'll observe certain arguments with hardcoded values. You use these to configure the parts of your component that never change.
+
+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).
+
+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.

package/docs/user_input.md

@@ -0,0 +1,64 @@
+# Blits - Lightning 3 App Development Framework
+
+## Handling User Input
+
+You don't want your Lightning 3 App to be completely static, instead users should be able to navigate and interact with the app, often using devices like a remote control.
+
+Blits offers a straightforward interface to handle user input for each component.
+
+### Configuring Input Handling
+
+Within the Component configuration object, the `input` key is utilized to define how the component should react to specific key presses when it has focus. It should contain an object of functions that specify the actions to take based on key presses.
+
+Each function should correspond to a key name, such as `up`, `down`, `enter`, `space`, `back`, `1`, `2`, `a` etc. Each function defined in the `input` object receives the full `InputEvent` object as its first argument.
+
+```javascript
+{
+  input: {
+    up() {
+      // Logic to execute when users press up
+    },
+    down() {
+      // Logic to execute when users press down
+    },
+    enter() {
+      // Logic to execute when users press enter
+    },
+  }
+}
+```
+
+### Event Handling Chain
+
+If the currently focused component does not handle a key press, the framework will traverse up the component hierarchy, checking if any parent components have defined functions for that key press in their `input`-object. This event handling chain continues until it reaches the root Application.
+
+When a component handles a key press by having a corresponding function specified, the event handling chain stops by default. However, if you want the input event to propagate up the hierarchy, you can set focus to the parent element and pass the `InputEvent` object on in the function call.
+
+```javascript
+{
+  input: {
+    enter() {
+      // Give focus to the parent
+      this.parent.focus();
+    },
+    back(e) {
+      // Give focus to the parent and let the user input event bubble
+      this.parent.focus(e);
+    },
+  }
+}
+```
+
+### Catch-All Handling
+
+To allow a focused component to respond to any key and act as a catch-all, you can add an `any()` function to the input object.
+
+```javascript
+{
+  input: {
+    any() {
+      // Logic to execute for any key press
+    },
+  }
+}
+```

package/docs/watchers.md

@@ -0,0 +1,38 @@
+# 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
+    }
+  },
+  watchers: {
+    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.

package/index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2023 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Component from './src/component.js'
+import Application from './src/application.js'
+import Launch from './src/launch.js'
+
+export default {
+  Component,
+  Application,
+  Launch,
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lightningjs/blits",
+  "version": "0.3.0",
+  "description": "Blits: The Lightning 3 App Development Framework",
+  "bin": "bin/index.cjs",
+  "exports": {
+    ".": "./index.js",
+    "./vite": "./vite/index.js"
+  },
+  "scripts": {
+    "test": "tape '{,!(node_modules)/**/}*.test.js' | tap-diff",
+    "lint": "eslint '**/*.js'",
+    "lint:fix": "eslint '**/*.js' --fix"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "type": "module",
+  "author": "Michiel van der Geest <hello@michielvandergeest.com>",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "babel-eslint": "^10.1.0",
+    "eslint": "^8.8.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "esm": "^3.2.25",
+    "husky": "^7.0.4",
+    "lint-staged": "^12.3.3",
+    "prettier": "^2.5.1",
+    "tap-diff": "^0.1.1",
+    "tape": "^5.5.0"
+  },
+  "dependencies": {
+    "@lightningjs/renderer": "^0.3.0",
+    "@lightningjs/vite-plugin-import-chunk-url": "^0.3.0"
+  }
+}

package/src/application.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2023 Comcast Cable Communications Management, LLC
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import Component from './component.js'
+
+import Focus from './focus.js'
+
+const Application = (config) => {
+  // make configurable?
+  const mapping = {
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+    ArrowUp: 'up',
+    ArrowDown: 'down',
+    Enter: 'enter',
+    ' ': 'space',
+    Backspace: 'back',
+  }
+
+  const handler = (e) => {
+    const key = mapping[e.key] || e.key
+    Focus.input(key, e)
+  }
+
+  document.addEventListener('keydown', handler)
+
+  config.hooks = config.hooks || {}
+  config.hooks.___init = function () {
+    Focus.set(this)
+  }
+
+  config.hooks.___destroy = function () {
+    document.removeEventListener('keydown', handler)
+  }
+
+  const App = Component('App', config)
+
+  return App
+}
+
+export default Application