@lightningjs/blits 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Changelog
 
+## v1.9.0
+
+_4 nov 2024_
+
+- Added Layout component
+
+## v1.8.3
+
+_31 oct 2024_
+
+- Exported TS interfaces and improved return type of before route hook
+- Fixed test cases for codegenerator
+
+
 ## v1.8.2
 
 _30 oct 2024_
 
-- Fixed edgecase issue with array based props not triggering reactivity
+- Fixed edge case issue with array based props not triggering reactivity
 
 
 ## v1.8.1

package/docs/_sidebar.md

@@ -23,6 +23,7 @@
 - Built-in components
   - [Directives](/built-in/directives.md)
   - [For loop](/built-in/for-loop.md)
+  - [Layout](/built-in/layout.md)
 - Plugins
   - [Text-to-Speech / Announcer](/plugins/text-to-speech-announcer.md)
   - [Language](/plugins/language.md)

package/docs/built-in/layout.md

@@ -0,0 +1,76 @@
+# Layout
+
+A big portion of building a pixel perfect App is all about correctly positioning Elements and Components on screen. In Lightning and Blits _absolute_ positions are used. This fits the whole concept of building a TV app where the viewport dimensions are known and fixed. Absolute positioning (versus spacing Elements relative to each other) is also more performant.
+
+Imagine a complex design with several nested layers. Relying solely on _relative_ positioning and elements automatically floating as space is available, may lead to heavy and recursive calculations. Then throw some dynamically changing dimensions and animations in the mix as well, and your App may be starting to noticeably drop frames due to expensive re-calculations.
+
+That being said, there are often cases where it becomes very cumbersome to calculate all the positions manually. Especially when dimensions are not known in advance and elements may load asynchronously.
+
+If you come from a CSS background, you may be tempted to say: "_this is why we have Flexbox!_". And while Flexbox is great and versatile in CSS and running on a powerful device, a full flexbox implementation does come at a cost and the risk of slowing down your App, when applied extensively or incorrectly.
+
+In order to address the core problem "_how do I easily position a bunch of Elements and Components, without writing a lot of code with `@loaded` event handlers_", Blits offers the built-in `<Layout>`-component - a basic and performant solution that automatically puts your Elements in the right place.
+
+## How to use
+
+Since the Layout-component is a built-in component, there is no need to register it separately. You can use the `<Layout>`-tag anywhere in your templates, just as you would use `<Element>` and `<Text>`.
+
+The Layout component is a wrapper component, that encloses a number of children. All the direct children that are wrapped in a `<Layout>`-tag are automatically positioned in order, one next to the other.
+
+Whenever the dimensions of a child change, the positioning of the next children is automatically recalculated and re-applied.
+
+```xml
+<Layout>
+  <Element w="40" h="40" color="red" />
+  <Element w="80" h="40" color="blue" />
+  <Text>Hello world</Text>
+  <Element w="40" h="40" color="green" />
+</Layout>
+```
+
+### Horizontal and vertical layout
+
+By default the Layout component lays out it's contents _horizontally_. The Layout component accepts a `direction` attribute which allows you to control the direction.
+
+In order to align vertically use `<Layout direction="vertical"></Layout>`. And use `<Layout direction="horizontal"></Layout>` to explicitly apply the default horizontal layout.
+
+### Spacing between children
+
+By default the Layout-component places each Element directly besides (or below) the previous one. By adding the `gap`-attribute you can control how much space will be added between each Element or Component. The `gap`-attribute accepts a number in pixels.
+
+### Dynamic dimensions
+
+For the Layout component to work properly, the direct children all need to have dimensions (i.e `w` and `h` attributes). The exception here being Text elements.
+
+Due to the asynchronous nature of rendering text, the final text dimensions are not known beforehand. The width and height of Text elements are automatically set when the text has been loaded. This fires a `@loaded` event, that you can tap into as described [here](../essentials/displaying_text#text-dimensions).
+
+The Layout component also uses this event, to execute its calculation and position the text and other elements around it properly.
+
+When the children of the Layout-component have _reactive_ dimensions (i.e. `<Element :w="$mywidth" :h="$myheight" />), the Layout component ensures that all child elements are properly re-positioned whenever a dimension changes.
+
+### Nesting Layouts
+
+It's also possible to nest layouts. Simply place a new `<Layout>`-tag, with it's own children in between the children of another Layout-component. The Layout-component itself will grow automatically with the dimensions of it's children. In other words, it's not required to specify a width (`w`) or height (`h`) on the `<Layout>`-tag itself.
+
+And of course you can nest _vertical_ Layouts inside a _horizontal_ one - and vice versa.
+
+### Transitioning layouts
+
+The `<Layout>`-component can also take into account when dimensions of children change with a transition applied to it. The component will recalculate the position of its children as the transition progresses, making sure that elements are always perfectly positioned relative to one another.
+
+## Performance
+
+The Layout-component is a very useful utility, that will make it a lot easier to put together complex layouts. It will reduce the code required, it means less hardcoding of values and removes the need to manually wire up `@loaded` events when working with dynamic / asynchronous elements.
+
+We've done our best to make the Component as performant as possible, by deliberately keeping it simple and straight forward. But it's important to understand that the Layout component does come at a cost. Depending on the use case these costs may be negligible, but there are cases where the Layout component might prove to be a bottle-neck.
+
+The performance costs may always be there to some degree. Whether it's the Layout component that does the complex calculations, or you do it in your custom code. So please feel encouraged to use the `<Layout>`-tag!
+
+Some pointers to keep in mind, though:
+
+- Every change in the dimensions of a child, triggers the Layout component to recalculate and reposition. If your child elements change frequently, the Layout component may have a performance impact.
+
+- The Layout component support transitions, but beware that when transitioning child dimensions a recalculation happens every frame-tick. If you see frame-drops in your App, you may want to see if the `<Layout>`-tag has an impact on this.
+
+- Be mindful to not apply unnecessary deep nesting of Layout tags. Each change in a deep child, will trigger recalculations up the tree of Layout tags.
+
+- When using the `<Layout>`-tag with a for-loop, it may be more performant to use the `$index` of the for-loop and manually position the elements yourself (i.e. `<Element :for="(item, index) in $items" :$x="$item * 200" w="150" h="150" />`). Especially if the dimensions are know before hand and possibly are the same for each child.

package/docs/sidebar.json

@@ -101,6 +101,10 @@
       {
         "text": "For loop",
         "link": "/built-in/for-loop"
+      },
+      {
+        "text": "Layout",
+        "link": "/built-in/layout.md"
       }
     ]
   },

package/index.d.ts

@@ -19,7 +19,7 @@ import {type ShaderEffect as RendererShaderEffect, type WebGlCoreShader} from '@
 
 declare module '@lightningjs/blits' {
 
-  interface Hooks {
+  export interface Hooks {
     /**
     * Fires when the Component is being instantiated
     * At this moment child elements will not be available yet
@@ -77,7 +77,7 @@ declare module '@lightningjs/blits' {
     exit?: () => void;
   }
 
-  interface Input {
+  export interface Input {
     [key: string]: (event: KeyboardEvent) => void | undefined,
     /**
      * Catch all input function
@@ -88,7 +88,7 @@ declare module '@lightningjs/blits' {
     any?: (event: KeyboardEvent) => void
   }
 
-  interface Log {
+  export interface Log {
     /**
     * Log an info message
     */
@@ -109,16 +109,16 @@ declare module '@lightningjs/blits' {
 
 
 
-  interface RouteData {
+  export interface RouteData {
     [key: string]: any
   }
 
   // todo: specify valid route options
-  interface RouteOptions {
+  export interface RouteOptions {
     [key: string]: any
   }
 
-  interface Router {
+  export interface Router {
     /**
      * Navigate to a different location
      *
@@ -148,7 +148,7 @@ declare module '@lightningjs/blits' {
 
   }
 
-  type ComponentBase = {
+  export type ComponentBase = {
     /**
     * Listen to events emitted by other components
     */
@@ -246,7 +246,7 @@ declare module '@lightningjs/blits' {
   /**
    * Prop object
    */
-  type PropObject = {
+  export type PropObject = {
     /**
      * Name of the prop
      */
@@ -274,7 +274,7 @@ declare module '@lightningjs/blits' {
   };
 
   // Props Array
-  type Props = (string | PropObject)[];
+  export type Props = (string | PropObject)[];
 
   // Extract the prop names from the props array
   type ExtractPropNames<P extends Props> = {
@@ -282,11 +282,11 @@ declare module '@lightningjs/blits' {
   };
 
   // Update the PropsDefinition to handle props as strings or objects
-  type PropsDefinition<P extends Props> = ExtractPropNames<P>;
+  export type PropsDefinition<P extends Props> = ExtractPropNames<P>;
 
-  type ComponentContext<P extends Props, S, M, C> = ThisType<PropsDefinition<P> & S & M & C & ComponentBase>
+  export type ComponentContext<P extends Props, S, M, C> = ThisType<PropsDefinition<P> & S & M & C & ComponentBase>
 
-  interface ComponentConfig<P extends Props, S, M, C, W> {
+  export interface ComponentConfig<P extends Props, S, M, C, W> {
     components?: {
         [key: string]: ComponentFactory,
     },
@@ -365,7 +365,7 @@ declare module '@lightningjs/blits' {
     watch?: W & ComponentContext<P, S, M, C>
   }
 
-  interface ApplicationConfig<P extends Props, S, M, C, W> extends ComponentConfig<P, S, M, C, W> {
+  export interface ApplicationConfig<P extends Props, S, M, C, W> extends ComponentConfig<P, S, M, C, W> {
     /**
      * Routes definition
      *
@@ -383,7 +383,7 @@ declare module '@lightningjs/blits' {
   }
 
 
-  interface Transition {
+  export interface Transition {
     /**
      * Name of the prop to transition (i.e. 'x', 'y', 'alpha', 'color')
      */
@@ -406,7 +406,7 @@ declare module '@lightningjs/blits' {
     delay?: number
   }
 
-  interface Before {
+  export interface Before {
     /**
     * Name of the prop to set before the transition starts
     */
@@ -417,7 +417,7 @@ declare module '@lightningjs/blits' {
     value: any,
   }
 
-  interface RouteTransition {
+  export interface RouteTransition {
     /**
      * Setting or Array of Settings before new view enters into the router view
      */
@@ -432,9 +432,9 @@ declare module '@lightningjs/blits' {
     out: Transition | Transition[],
   }
 
-  type RouteTransitionFunction = (previousRoute: Route, currentRoute: Route) => RequireAtLeastOne<RouteTransition>
+  export type RouteTransitionFunction = (previousRoute: Route, currentRoute: Route) => RequireAtLeastOne<RouteTransition>
 
-  interface RouteAnnounce {
+  export interface RouteAnnounce {
     /**
      * Message to be announced
      */
@@ -447,15 +447,15 @@ declare module '@lightningjs/blits' {
     politeness?: 'off' | 'polite' | 'assertive'
   }
 
-  type RequireAtLeastOne<T> = {
+  export type RequireAtLeastOne<T> = {
     [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>
   }[keyof T]
 
-  interface RouteHooks {
-    before?: (to: Route, from: Route) => string | Route;
+  export interface RouteHooks {
+    before?: (to: Route, from: Route) => string | Route | Promise<string | Route>;
   }
 
-  type Route = {
+  export type Route = {
     /**
      * URI path for the route
      */
@@ -575,7 +575,7 @@ declare module '@lightningjs/blits' {
    * Launcher function that sets up the Lightning renderer and instantiates
    * the Blits App
    */
-  interface Settings {
+  export interface Settings {
     /**
      * Width of the Application
      */

package/package.json

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

package/src/components/index.js

@@ -19,12 +19,10 @@ import Circle from './Circle.js'
 import RouterView from './RouterView.js'
 import Sprite from './Sprite.js'
 import FPScounter from './FPScounter.js'
-import Layout from './Layout.js'
 
 export default () => ({
   Circle: Circle(),
   RouterView: RouterView(),
   Sprite: Sprite(),
   FPScounter: FPScounter(),
-  Layout: Layout(),
 })

package/src/components/index.orig.js

@@ -19,12 +19,10 @@ import Circle from './Circle.js'
 import RouterView from './RouterView.js'
 import Sprite from './Sprite.js'
 import FPScounter from './FPScounter.js'
-import Layout from './Layout.js'
 
 export default () => ({
   Circle: Circle(),
   RouterView: RouterView(),
   Sprite: Sprite(),
   FPScounter: FPScounter(),
-  Layout: Layout(),
 })

package/src/engines/L3/element.js

@@ -22,6 +22,38 @@ import { Log } from '../../lib/log.js'
 import symbols from '../../lib/symbols.js'
 import Settings from '../../settings.js'
 
+const layoutFn = function (config) {
+  let offset = 0
+  const xy = config.direction === 'vertical' ? 'y' : 'x'
+  const wh = config.direction === 'vertical' ? 'height' : 'width'
+  const opositeWh = config.direction === 'vertical' ? 'width' : 'height'
+
+  const children = this.children
+  const childrenLength = children.length
+  let otherDimension = 0
+  for (let i = 0; i < childrenLength; i++) {
+    const node = children[i]
+    node[xy] = offset
+    // todo: temporary text check, due to 1px width of empty text node
+    if (wh === 'width') {
+      offset += node.width + (node.width !== ('text' in node ? 1 : 0) ? config.gap : 0)
+    } else if (wh === 'height') {
+      offset +=
+        'text' in node
+          ? node.width > 1
+            ? node.height + config.gap
+            : 0
+          : node.height !== 0
+          ? node.height + config.gap
+          : 0
+    }
+    otherDimension = Math.max(otherDimension, node[opositeWh])
+  }
+  // adjust the size of the layout container
+  this[wh] = offset - (config.gap || 0)
+  this[opositeWh] = otherDimension
+}
+
 const isTransition = (value) => {
   return value !== null && typeof value === 'object' && 'transition' in value === true
 }
@@ -305,11 +337,16 @@ const Element = {
       })
     }
 
-    // if (this.component !== undefined && '___layout' in this.component) {
-    //   this.node.on('loaded', () => {
-    //     this.component.___layout()
-    //   })
-    // }
+    if (props.__layout === true) {
+      this.triggerLayout = layoutFn.bind(this.node)
+    }
+
+    if (this.config.parent.props !== undefined && this.config.parent.props.__layout === true) {
+      this.config.parent.triggerLayout(this.config.parent.props)
+      this.node.on('loaded', () => {
+        this.config.parent.triggerLayout(this.config.parent.props)
+      })
+    }
   },
   set(prop, value) {
     if (value === undefined) return
@@ -338,10 +375,9 @@ const Element = {
       }
     }
 
-    // todo: review naming
-    // if (this.component && this.component.___layout) {
-    //   this.component.___layout()
-    // }
+    if (this.config.parent.props && this.config.parent.props.__layout === true) {
+      this.config.parent.triggerLayout(this.config.parent.props)
+    }
   },
   animate(prop, value, transition) {
     // check if a transition is already scheduled to run on the same prop
@@ -393,6 +429,12 @@ const Element = {
       })
     }
 
+    if (this.config.parent.props && this.config.parent.props.__layout === true) {
+      f.on('tick', () => {
+        this.config.parent.triggerLayout(this.config.parent.props)
+      })
+    }
+
     if (transition.progress !== undefined && typeof transition.progress === 'function') {
       let prevProgress = 0
       f.on('tick', (_node, { progress }) => {

package/src/lib/codegenerator/generator.js

@@ -414,9 +414,6 @@ const generateForLoopCode = function (templateObject, parent) {
       `)
     }
   })
-  // if(elms[${forStartCounter}][0] && elms[${forStartCounter}][0].forComponent && elms[${forStartCounter}][0].forComponent.___layout) {
-  //   elms[${forStartCounter}][0].forComponent.___layout()
-  // }
   ctx.renderCode.push(`
     }
   }`)
@@ -498,11 +495,15 @@ const generateCode = function (templateObject, parent = false, options = {}) {
         if (
           childTemplateObject[Symbol.for('componentType')] === 'Element' ||
           childTemplateObject[Symbol.for('componentType')] === 'Slot' ||
-          childTemplateObject[Symbol.for('componentType')] === 'Text'
+          childTemplateObject[Symbol.for('componentType')] === 'Text' ||
+          childTemplateObject[Symbol.for('componentType')] === 'Layout'
         ) {
           if (childTemplateObject[Symbol.for('componentType')] === 'Text') {
             childTemplateObject.__textnode = 'true'
           }
+          if (childTemplateObject[Symbol.for('componentType')] === 'Layout') {
+            childTemplateObject.__layout = 'true'
+          }
           generateElementCode.call(this, childTemplateObject, parent, options)
         } else {
           generateComponentCode.call(this, childTemplateObject, parent, options)