@lightningjs/blits 0.3.7 → 0.3.8

package/.vscode/extensions.json

@@ -2,5 +2,6 @@
 	"recommendations": [
 		"editorconfig.editorconfig",
 		"dbaeumer.vscode-eslint",
+    "LightningJS.lightning-blits"
 	]
 }

package/boilerplate/.vscode/extensions.json

@@ -2,6 +2,7 @@
 	"recommendations": [
 		"editorconfig.editorconfig",
 		"dbaeumer.vscode-eslint",
-    "naumovs.color-highlight"
+    "naumovs.color-highlight",
+    "LightningJS.lightning-blits"
 	]
 }

package/boilerplate/.vscode/settings.json

@@ -5,5 +5,6 @@
     ],
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true
-    }
+    },
+    "js/ts.implicitProjectConfig.checkJs": true
   }

package/boilerplate/src/fontloader.js

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

package/boilerplate/src/index.js

@@ -1,9 +1,10 @@
 import Blits from '@lightningjs/blits'
+// @ts-ignore
 import fontLoader from './fontloader.js?importChunkUrl'
 
 import App from './App.js'
 
-const settings = {
+Blits.Launch(App, 'app', {
   w: 1920,
   h: 1080,
   multithreaded: false,
@@ -14,6 +15,4 @@ const settings = {
     {family: 'raleway', type: 'msdf', png: '/fonts/Raleway-ExtraBold.msdf.png', json: '/fonts/Raleway-ExtraBold.msdf.json'},
     {family: 'opensans', type: 'web', file: '/fonts/OpenSans-Medium.ttf'}
   ],
-}
-
-Blits.Launch(App, 'app', settings)
+})

package/boilerplate/src/renderer.js

@@ -1,3 +1,4 @@
+// @ts-ignore
 import renderer from '@lightningjs/blits/renderer'
 
 renderer()

package/index.d.ts

@@ -0,0 +1,31 @@
+/*
+ * 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'
+
+/**
+ * Blits - The Lightning 3 App Development Framework
+ */
+declare module Blits {
+  export { Component }
+  export { Application }
+  export { Launch }
+}
+
+export default Blits

package/package.json

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

package/src/application.d.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 {default as Component, ComponentInstance} from './component'
+
+declare namespace Application {
+
+  interface Route {
+    /**
+     * URI path for the route
+     */
+    path: string,
+    /**
+     * Component to load when activating the route
+     */
+    component: typeof ComponentInstance
+  }
+
+  export interface ApplicationInstance extends ComponentInstance {}
+
+  export interface ApplicationConfig extends Component.ComponentConfig {
+    /**
+     * Routes definition
+     *
+     * @example
+     *
+     * ```js
+     * routes: [
+     *  { path: '/', component: Home },
+     *  { path: '/details', component: Details },
+     *  { path: '/account', component: Account },
+     * ]
+     * ```
+     */
+    routes: Route[]
+  }
+}
+
+/**
+ * Blits.Application()
+ *
+ * Root App component
+ */
+declare function Application(
+  config: Application.ApplicationConfig
+) : Application.ApplicationInstance
+
+export default Application;

package/src/component.d.ts

@@ -0,0 +1,273 @@
+/*
+ * 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
+ */
+
+declare namespace Component {
+
+  /**
+   * Name of the Component
+   */
+  type Name = string
+
+  interface AdvancedProp {
+    /**
+     * Name of the prop
+     */
+    key: string,
+    /**
+     * Whether the prop is required to be passed
+     */
+    required?: boolean,
+    /**
+     * Default value for the prop when omited
+     */
+    default?: any,
+    /**
+     * Cast the value of the prop
+     *
+     * @example
+     * ```js
+     * {
+     *   cast: Number, // casts to a number
+     *   cast: (v) => v.toUpperCase() // casts to uppercase
+     * }
+     * ```
+     */
+    cast?: () => any
+  }
+
+  type Props = string | AdvancedProp
+
+  type NotFunction<T> = T extends Function ? never : T;
+
+  /**
+   * Internal state of a Component instance
+   */
+  interface StateObject {
+    [key: string]: any
+  }
+
+  interface Computed {
+    [key: string]: (this: ComponentInstance) => any
+  }
+
+  interface Watch {
+    [key: string]: (this: ComponentInstance, value: any, oldValue: any) => void
+  }
+
+  interface Methods {
+    [key: string]: (this: ComponentInstance) => any
+  }
+
+  interface Input {
+    [key: string]: (this: ComponentInstance, event: KeyboardEvent) => void,
+    /**
+     * Catch all input function
+     *
+     * Will be invoked when there is no dedicated function for a certain key
+     */
+    'any'?: (this: ComponentInstance, event: KeyboardEvent) => void,
+  }
+
+  interface Log {
+    /**
+    * Log an info message
+    */
+    info: typeof console.info
+    /**
+    * Log an error message
+    */
+    error: typeof console.error
+    /**
+    * Log a warning
+    */
+    warn: typeof console.warn
+    /**
+    * Log a debug message
+    */
+    debug: typeof console.debug
+  }
+
+  interface Hooks {
+    /**
+    * Fires when the Component is being instantiated.
+    * At this moment child elements will not be available yet
+    */
+    init?: (this: ComponentInstance) => void
+    /**
+    * Fires when the Component is fully initialized and ready for interaction.
+    */
+    ready?: (this: ComponentInstance) => void
+    /**
+    * Triggers when the Component receives focus.
+    * This event can fire multiple times during the component's lifecycle
+    */
+    focus?: (this: ComponentInstance) => void
+    /**
+    * Triggers when the Component loses focus.
+    * This event can fire multiple times during the component's lifecycle
+    */
+    unfocus?: (this: ComponentInstance) => void
+    /**
+    * Fires when the Component is being destroyed and removed.
+    */
+    destroy?: (this: ComponentInstance) => void
+  }
+
+  export interface ComponentInstance {
+    /**
+    * Listen to events emitted by other components
+    */
+    $listen: (event: string, callback: (args: any) => void) => void
+
+    /**
+    * Emit events that other components can listen to
+    */
+    $emit: (event: string, args?: any) => void
+
+    /**
+    * Set a timeout that is automatically cleaned upon component destroy
+    */
+    $setTimeout: (callback: (args: any) => void, ms?: number | undefined) => typeof setTimeout
+
+    /**
+    * Set an interval that is automatically cleaned upon component destroy
+    */
+    $setInterval: (callback: (args: any) => void, ms?: number | undefined) => typeof setInterval
+
+    /**
+    * Log to the console with prettier output and configurable debug levels in Settings
+    */
+    $log: Log
+
+    /**
+    * Set focus to the Component, optionally pass a KeyboardEvent for instant event bubbling
+    */
+    focus: (event?: KeyboardEvent) => void
+
+    /**
+    * Select a child Element or Component by ref
+    *
+    * Elements and Components in the template can have an optional ref argument.
+    * Returns an Element Instance or Component Instance.
+    * Useful for passing on the focus to a Child component.
+    *
+    * @example
+    * ```js
+    * const menu = this.select('Menu')
+    * if(menu) {
+    *   menu.focus()
+    * }
+    * ```
+    */
+    select: (ref: string) => ComponentInstance | ElementInstance
+
+    // tmp
+    [key: string]: any
+  }
+
+  export interface ElementInstance {
+    focus?: () => void
+  }
+
+  export interface ComponentConfig {
+    components?: any,
+    /**
+     * XML-based template string of the Component
+     *
+     * @example
+     * ```xml
+     * <Element :x="$x" w="400" h="1080" color="#64748b">
+     *  <Element x="50" y="40">
+     *   <Button color="#e4e4e7" />
+     *   <Button color="#e4e4e7" y="100" />
+     *   <Button color="#e4e4e7" y="200" />
+     *   <Button color="#e4e4e7" y="300" />
+     *  </Element>
+     * </Element>
+     * ```
+     */
+    template?: String,
+    /**
+     * Reactive internal state of the Component instance
+     *
+     * Should return an object (literal) with key value pairs.
+     * Can contain nested objects, but beware that too deep nesting can have
+     * a negative impact on performance
+     *
+     * @example
+     * ```js
+     * state() {
+     *  return {
+     *    items: [],
+     *    color: 'red',
+     *    alpha: 0.1
+     *  }
+     * }
+     * ```
+     */
+    state?: (this: ComponentInstance) => StateObject,
+    /**
+     * Allowed props to be passed into the Component by the parent
+     *
+     * Can be a simple array with `prop` keys as strings.
+     * Alternatively objects can be used to specify `required` props and `default` values
+     *
+     * @example
+     * ```js
+     * props: ['index', {
+     *  key: 'alpha',
+     *  required: true
+     * }, {
+     *  key: 'color',
+     *  default: 'red'
+     * }]
+     * ```
+     */
+    props?: Props[],
+    /**
+     * Computed properties
+     */
+    computed?: Computed,
+    /**
+     * Watchers for changes to state variables, props or computed properties
+     */
+    watch?: Watch,
+    /**
+     * Hooking into Lifecycle events
+     */
+    hooks?: Hooks,
+    /**
+     * Methods for abstracting more complex business logic into separate function
+     */
+    methods?: Methods,
+    /**
+     * Tapping into user input
+     */
+    input?: Input
+  }
+}
+
+
+ /**
+ * Blits.Component()
+ */
+declare function Component(
+  name: Component.Name,
+  config: Component.ComponentConfig,
+) : Component.ComponentInstance
+
+export default Component;

package/src/launch.d.ts

@@ -0,0 +1,105 @@
+/*
+ * 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 ApplicationInstance from './application'
+
+interface WebFont {
+  /**
+  * Name of the font family
+  */
+  family: string,
+  /**
+  * Type of font (web)
+  */
+  type: 'web',
+  /**
+  * Location to the font file (i.e. `/fonts/OpenSans-Medium.ttf`)
+  */
+  file: string
+}
+
+interface SdfFont {
+  /**
+  * Name of the font family
+  */
+  family: string,
+  /**
+  * Type of font (msdf or sdf)
+  */
+  type: 'msdf' | 'sdf',
+  /**
+  * Location of the font map (i.e. `'/fonts/Lato-Regular.msdf.json'`)
+  */
+  json: string,
+  /**
+  * Location of the font png (i.e. `'/fonts/Lato-Regular.msdf.png'`)
+  */
+  png: string
+}
+
+type Font = WebFont | SdfFont
+
+export type DebugLevel = 0 | 1 | 2
+export type LogTypes = 'info' | 'warn' | 'error' | 'debug'
+
+/**
+ * Settings
+ *
+ * Launcher function that sets up the Lightning renderer and instantiates
+ * the Blits App
+ */
+export interface Settings {
+  /**
+   * Width of the Application
+   */
+  w?: number,
+  /**
+   * Height of the Application
+   */
+  h?: number,
+  /**
+   * Whether to enable multithreaded
+   */
+  multithreaded?: boolean,
+  /**
+   * Debug level for console log messages
+   */
+  debugLevel?: DebugLevel | LogType[]
+  /**
+   * Font loader file
+   */
+  fontLoader?: any
+  /**
+   * Fonts to be used in the Application
+   */
+  fonts?: Font[]
+}
+
+/**
+ * Blits.Launch()
+ *
+ * Launcher function that sets up the Lightning renderer and instantiates
+ * the Blits App
+ */
+declare function Launch(
+  App: ApplicationInstance,
+  target: HTMLElement | string,
+  settings?: Settings,
+) : void
+
+
+export default Launch;