@lightningjs/blits 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v1.1.0
+
+_25 july 2024_
+
+- Made `holdTimeout` configurable and added to launch settings
+- Improved test coverage
+- Removed imporChunkUrl dependency as it’s no longer needed
+- Abstracted path from pre-compiler, to make it more reusable (in playground for example)
+- Added `defaultFont` launch setting to boilerplate example
+
 ## v1.0.0
 
 _15 july 2024_

package/boilerplate/js/default/src/index.js

@@ -6,6 +6,7 @@ Blits.Launch(App, 'app', {
   h: 1080,
   multithreaded: false,
   debugLevel: 1,
+  defaultFont: 'lato',
   fonts: [
     {
       family: 'lato',

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@lightningjs/blits",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Blits: The Lightning 3 App Development Framework",
   "bin": "bin/index.js",
   "exports": {
     ".": "./index.js",
     "./vite": "./vite/index.js",
-    "./transitions": "./src/router/transitions/index.js"
+    "./transitions": "./src/router/transitions/index.js",
+    "./precompiler": "./src/lib/precompiler/precompiler.js"
   },
   "scripts": {
     "test": "c8 npm run test:run",
@@ -46,7 +47,6 @@
   "dependencies": {
     "@lightningjs/msdf-generator": "^1.0.2",
     "@lightningjs/renderer": "^1.0.0",
-    "@lightningjs/vite-plugin-import-chunk-url": "^0.3.0",
     "execa": "^8.0.1",
     "kolorist": "^1.8.0",
     "ora": "^7.0.1",

package/src/application.js

@@ -20,6 +20,7 @@ import Focus from './focus.js'
 import Settings from './settings.js'
 
 import symbols from './lib/symbols.js'
+import { DEFAULT_HOLD_TIMEOUT_MS } from './constants.js'
 
 const Application = (config) => {
   const defaultKeyMap = {
@@ -61,7 +62,7 @@ const Application = (config) => {
       clearTimeout(holdTimeout)
       holdTimeout = setTimeout(() => {
         Focus.hold = true
-      }, 50)
+      }, Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS))
     }
 
     keyUpHandler = () => {

package/src/component.test.js

@@ -17,6 +17,12 @@
 
 import test from 'tape'
 import Component from './component.js'
+import { initLog } from './lib/log.js'
+import symbols from './lib/symbols.js'
+import util from 'node:util'
+import { renderer, stage } from './launch.js'
+
+initLog()
 
 test('Type', (assert) => {
   const expected = 'function'
@@ -37,15 +43,345 @@ test('Component - Factory function', (assert) => {
 test('Component - Factory requires a name to be passed', (assert) => {
   assert.throws(() => {
     Component()
-  }, 'Thorw an error when no name argument has been passed')
+  }, 'Throw an error when no name argument has been passed')
 
   assert.end()
 })
 
-test('Component - Factory requires a name to be passed', (assert) => {
+test('Component - Factory requires a config to be passed', (assert) => {
   assert.throws(() => {
-    Component()
-  }, 'Throw an error when no name argument has been passed')
+    Component('Foo')
+  }, 'Throw an error when no config argument has been passed')
+
+  assert.end()
+})
+
+test('Component - Instance should create internal id', (assert) => {
+  const button = Component('Button', {})()
+  const heading = Component('Heading', {})()
+
+  assert.equal(button[symbols.id], 1, 'Button instance object should have correct internal id')
+  assert.equal(heading[symbols.id], 2, 'Heading instance object should have correct internal id')
+  assert.end()
+})
+
+test('Component - Instance should create component Id', (assert) => {
+  const foo = Component('Foo', {})
+  const bar = Component('Bar', {})
+  const fooInstance0 = foo()
+  const fooInstance1 = foo()
+  const barInstance0 = bar()
+
+  assert.equal(
+    fooInstance0.componentId,
+    'BlitsComponent::Foo_1',
+    'First Foo instance should have correct id'
+  )
+  assert.equal(
+    fooInstance1.componentId,
+    'BlitsComponent::Foo_2',
+    'Second Foo instance should have correct id'
+  )
+  assert.equal(
+    barInstance0.componentId,
+    'BlitsComponent::Bar_1',
+    'First Bar instance should have correct id'
+  )
+  assert.end()
+})
+
+test('Component - Instance should initiate lifecycle object', (assert) => {
+  const foo = Component('Foo', {})()
+
+  assert.ok(foo.lifecycle, 'Lifecycle object should be initialized')
+  assert.equal(
+    foo.lifecycle.component,
+    foo,
+    'Lifecycle object should have a reference to foo instance'
+  )
+  assert.equal(
+    foo.lifecycle.previous,
+    null,
+    'Lifecycle object should have previous state not initialized'
+  )
+  assert.equal(foo.lifecycle.current, 'init', 'Lifecycle object should have initial current state')
+  assert.end()
+})
+
+test('Component - Instance should set a parent reference', (assert) => {
+  const parentElement = {}
+  const parentComponent = {}
+
+  const foo = Component('Foo', {})({}, parentElement, parentComponent)
+
+  assert.equal(
+    foo.parent,
+    parentComponent,
+    'Foo instance object should have parent component object reference'
+  )
+  assert.equal(
+    foo[symbols.holder],
+    parentElement,
+    'Foo instance object should have parent element object reference'
+  )
+  assert.end()
+})
+
+test('Component - Instance should set a root reference', (assert) => {
+  const root = {}
+
+  const foo = Component('Foo', {})({}, {}, {}, root)
+
+  assert.equal(
+    foo.rootParent,
+    root,
+    'Foo instance object should have root component object reference'
+  )
+  assert.end()
+})
+
+test('Component - Instance should initialize reactive props', (assert) => {
+  const foo = Component(
+    'Foo',
+    {}
+  )({
+    props: { foo: 'bar' },
+  })
+
+  const props = foo[symbols.props]
+
+  assert.ok(props, 'Foo instance should have props defined')
+  assert.ok(util.types.isProxy(props), 'Foo instance props should be proxy')
+  assert.equal(props.foo, 'bar')
+  assert.end()
+})
+
+test('Component - Instance should initialize timeouts array', (assert) => {
+  const foo = Component('Foo', {})()
+
+  const timeouts = foo[symbols.timeouts]
+
+  assert.ok(Array.isArray(timeouts), 'Foo instance timeouts should be an array')
+  assert.end()
+})
+
+test('Component - Instance should initialize intervals array', (assert) => {
+  const foo = Component('Foo', {})()
+
+  const intervals = foo[symbols.intervals]
 
+  assert.ok(Array.isArray(intervals), 'Foo instance intervals should be an array')
   assert.end()
 })
+
+test('Component - Instance should initialize originalState', (assert) => {
+  const config = {
+    state() {
+      return {
+        foo: 'bar',
+      }
+    },
+  }
+  const foo = Component('Foo', config)()
+
+  const state = foo[symbols.originalState]
+
+  assert.equal(state.foo, 'bar', 'Foo instance should store originalState properties')
+  assert.equal(state.hasFocus, false, 'Foo instance should store originalState hasFocus property')
+  assert.end()
+})
+
+test('Component - Instance should initialize reactive state', (assert) => {
+  const config = {
+    state() {
+      return {
+        foo: 'bar',
+      }
+    },
+  }
+  const foo = Component('Foo', config)()
+
+  const state = foo[symbols.state]
+
+  assert.ok(state, 'Foo instance should have state defined')
+  assert.ok(util.types.isProxy(state), 'Foo instance state should be proxy')
+  assert.equal(state.foo, 'bar')
+  assert.end()
+})
+
+test('Component - Instance should initialize children', (assert) => {
+  const parent = {}
+  const expected = []
+  const config = {
+    code: {
+      render: () => {},
+      effects: [],
+    },
+    state() {
+      return {
+        foo: 'bar',
+      }
+    },
+  }
+  const capture = assert.capture(config.code, 'render', () => expected)
+  const foo = Component('Foo', config)({}, parent)
+
+  const children = foo[symbols.children]
+
+  assert.ok(Array.isArray(children), 'Foo instance children should be an array')
+  assert.equal(children, expected, 'Children should be an expected array')
+  const args = capture()[0].args
+  assert.equal(args[0], parent, 'Render should be called with parent parameter')
+  assert.equal(args[1], foo, 'Render should be called with Foo component instance')
+  assert.equal(args[2], config, 'Render should be called with config parameter')
+  assert.ok(args[3].Layout, 'Render should be called with global components object')
+  assert.end()
+})
+
+test('Component - Instance should initialize wrapper', (assert) => {
+  const expected = {}
+  const config = {
+    code: {
+      render: () => [expected],
+      effects: [],
+    },
+  }
+  const foo = Component('Foo', config)()
+
+  const wrapper = foo[symbols.wrapper]
+
+  assert.equal(wrapper, expected, 'Wrapper should be a first element of the children')
+  assert.end()
+})
+
+test('Component - Instance should initialize slots', (assert) => {
+  const expected = {
+    [symbols.isSlot]: true,
+  }
+  const config = {
+    code: {
+      render: () => [{}, {}, expected, {}],
+      effects: [],
+    },
+  }
+  const foo = Component('Foo', config)()
+
+  const slots = foo[symbols.slots]
+
+  assert.ok(Array.isArray(slots), 'Slots should be an array')
+  assert.equal(slots[0], expected, 'Slot should be a expected element of the children')
+  assert.end()
+})
+
+test('Component - Instance should initialize hook events', (assert) => {
+  const wrapper = {
+    node: {
+      on() {},
+    },
+  }
+  const rendererCapture = assert.capture(renderer, 'on')
+  const nodeCapture = assert.capture(wrapper.node, 'on')
+  const config = {
+    code: {
+      render: () => [wrapper],
+      effects: [],
+    },
+    hooks: {
+      frameTick() {},
+      idle() {},
+      attach() {},
+      detach() {},
+      enter() {},
+      exit() {},
+    },
+  }
+  Component('Foo', config)()
+
+  const rendererCalls = rendererCapture()
+  assert.equal(
+    rendererCalls[0].args[0],
+    'frameTick',
+    '`frameTick` event should be registered in Renderer'
+  )
+  assert.equal(rendererCalls[1].args[0], 'idle', '`idle` event should be registered in Renderer')
+  const nodeCalls = nodeCapture()
+  assert.equal(
+    nodeCalls[0].args[0],
+    'inBounds',
+    '`inBounds` event should be registered in the wrapper'
+  )
+  assert.equal(
+    nodeCalls[1].args[0],
+    'outOfBounds',
+    '`outOfBounds` event should be registered in the wrapper'
+  )
+  assert.equal(
+    nodeCalls[2].args[0],
+    'inViewport',
+    '`inViewport` event should be registered in the wrapper'
+  )
+  assert.equal(
+    nodeCalls[3].args[0],
+    'outOfViewport',
+    '`outOfViewport` event should be registered in the wrapper'
+  )
+  assert.end()
+})
+
+test('Component - Instance should execute all side effects', (assert) => {
+  const root = {}
+  const capture = assert.captureFn(() => {})
+  const children = []
+  const config = {
+    code: {
+      render: () => children,
+      effects: [capture],
+    },
+  }
+  const foo = Component('Foo', config)({}, {}, {}, root)
+
+  const calls = capture.calls[0]
+  assert.equals(calls.receiver, stage, 'Effect`s receiver should be the stage object')
+  assert.equals(calls.args[0], foo, 'Effect should be invoked with foo component instance')
+  assert.equals(calls.args[1], children, 'Effect should be invoked with component`s children')
+  assert.equals(calls.args[2], config, 'Effect should be invoked with config object')
+  assert.ok(calls.args[3].Layout, 'Effect should be invoked with global components object')
+  assert.equals(calls.args[4], root, 'Effect should be invoked with root component')
+  assert.ok(typeof calls.args[5] === 'function', 'Effect should be invoked with effect function')
+  assert.end()
+})
+
+test('Component - Instance should have all symbols configured', (assert) => {
+  const config = {
+    state() {
+      return {
+        foo: 'bar',
+      }
+    },
+    watch: {
+      foo(value, oldValue) {},
+    },
+  }
+  const foo = Component('Foo', config)()
+
+  Object.getOwnPropertySymbols(foo).forEach((symbol) => {
+    const descriptor = Object.getOwnPropertyDescriptor(foo, symbol)
+    assert.ok(descriptor.enumerable === false, `${symbol.description} should not be enumerable`)
+    assert.ok(descriptor.configurable === false, `${symbol.description} should not be configurable`)
+  })
+  assert.end()
+})
+
+test('Component - Instance should have ready state after the next process tick', (assert) => {
+  assert.plan(1)
+
+  const foo = Component('Foo', {})()
+
+  setTimeout(() => {
+    assert.equal(
+      foo.lifecycle.state,
+      'ready',
+      'Foo component lifecycle should be eventually in a ready state'
+    )
+  })
+})

package/src/constants.js

@@ -0,0 +1,14 @@
+export const DEFAULT_HOLD_TIMEOUT_MS = 50
+
+export const SCREEN_RESOLUTIONS = {
+  hd: 0.66666667,
+  '720p': 0.66666667,
+  720: 0.66666667,
+  fhd: 1,
+  fullhd: 1,
+  '1080p': 1,
+  1080: 1,
+  '4k': 2,
+  '2160p': 2,
+  2160: 2,
+}

package/src/engines/L3/launch.js

@@ -17,7 +17,7 @@
 
 import { RendererMain } from '@lightningjs/renderer'
 import { Log } from '../../lib/log.js'
-import { screenResolutions } from '../../lib/utils.js'
+import { SCREEN_RESOLUTIONS } from '../../constants.js'
 import colors from '../../lib/colors/colors.js'
 import fontLoader from './fontLoader.js'
 import shaderLoader from './shaderLoader.js'
@@ -42,8 +42,8 @@ You can remove the option from your \`src/index.js\`-file. And you can safely re
       fpsUpdateInterval: settings.fpsInterval || 1000,
       deviceLogicalPixelRatio:
         settings.pixelRatio ||
-        screenResolutions[settings.screenResolution] ||
-        screenResolutions[window.innerHeight] ||
+        SCREEN_RESOLUTIONS[settings.screenResolution] ||
+        SCREEN_RESOLUTIONS[window.innerHeight] ||
         1,
       numImageWorkers:
         'webWorkersLimit' in settings

package/src/focus.js

@@ -17,6 +17,8 @@
 
 import symbols from './lib/symbols.js'
 import { navigating } from './router/router.js'
+import Settings from './settings.js'
+import { DEFAULT_HOLD_TIMEOUT_MS } from './constants.js'
 
 let focusedComponent = null
 let focusChain = []
@@ -48,8 +50,7 @@ export default {
             focusChain = []
           }
         },
-        // todo: make the hold timeout configurable?
-        this.hold ? 50 : 0
+        this.hold ? Settings.get('holdTimeout', DEFAULT_HOLD_TIMEOUT_MS) : 0
       )
     }
   },

package/src/launch.d.ts

@@ -243,7 +243,18 @@ export interface Settings {
    *
    * Defaults to `webgl`
    */
-  renderMode?: RenderModes
+  renderMode?: RenderModes,
+
+  /**
+   * The time, in milliseconds, after which Blits considers a key press a _hold_ key press
+   *
+   * During a hold key press the focus delegation behaviour is different: when scrolling
+   * through a long list, focus is not handed over to each individual list item, creating a
+   * smoother experience
+   *
+   * Defaults to `50` (ms)
+   */
+  holdTimeout?: number
 }
 
 /**

package/src/launch.js

@@ -19,7 +19,7 @@ import Settings from './settings.js'
 import { initLog } from './lib/log.js'
 import engine from './engine.js'
 
-export let renderer
+export let renderer = {}
 export const stage = {}
 
 export default (App, target, settings) => {

package/src/lib/componentId.js

@@ -25,3 +25,12 @@ export const createHumanReadableId = (name) => {
 export const createInternalId = () => {
   return ++counter
 }
+
+/**
+ * Resets the counter value back to 0.
+ * Used in automated tests to ensure consistent results, not intended
+ * to be used in the actual framework code!
+ */
+export const resetCounter = () => {
+  counter = 0
+}

package/src/lib/componentId.test.js

@@ -16,7 +16,7 @@
  */
 
 import test from 'tape'
-import { createHumanReadableId, createInternalId } from './componentId.js'
+import { createHumanReadableId, createInternalId, resetCounter } from './componentId.js'
 
 test('Type createHumandReadableId', (assert) => {
   const expected = 'function'
@@ -59,6 +59,7 @@ test('Type createInternalId', (assert) => {
 })
 
 test('Returns an internal id, disregarding the component name', (assert) => {
+  resetCounter()
   const expected = 1
   const actual = createInternalId('Spinner')
 

package/src/lib/precompiler/precompiler.js

@@ -17,7 +17,6 @@
 
 import parser from '../templateparser/parser.js'
 import generator from '../codegenerator/generator.js'
-import path from 'path'
 
 export default (source, filePath) => {
   if (
@@ -46,8 +45,7 @@ export default (source, filePath) => {
           resourceName = source.match(/Blits\.Component\(['"](.*)['"]\s*,/)[1]
         }
 
-        const componentPath = path.relative(process.cwd(), filePath)
-        const parsed = parser(templateContent, resourceName, null, componentPath)
+        const parsed = parser(templateContent, resourceName, null, filePath)
 
         // Generate the code
         const code = generator.call({ components: {} }, parsed)

package/vite/index.js

@@ -15,13 +15,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { importChunkUrl } from '@lightningjs/vite-plugin-import-chunk-url'
-
 import preCompiler from './preCompiler.js'
 import msdfGenerator from './msdfGenerator.js'
 
-export { importChunkUrl as importChunkUrl } from '@lightningjs/vite-plugin-import-chunk-url'
 export { default as preCompiler } from './preCompiler.js'
 export { default as msdfGenerator } from './msdfGenerator.js'
 
-export default [importChunkUrl(), preCompiler(), msdfGenerator()]
+export default [preCompiler(), msdfGenerator()]

package/vite/preCompiler.js

@@ -16,6 +16,7 @@
  */
 
 import compiler from '../src/lib/precompiler/precompiler.js'
+import path from 'path'
 
 export default function () {
   let config
@@ -26,7 +27,8 @@ export default function () {
     },
     transform(source, filePath) {
       if (config.blits && config.blits.precompile === false) return source
-      return compiler(source, filePath)
+      const relativePath = path.relative(process.cwd(), filePath)
+      return compiler(source, relativePath)
     },
   }
 }