@lightningjs/blits 1.7.0 → 1.8.0

package/src/component.d.ts

@@ -1,455 +0,0 @@
-/*
- * 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 Announcer {
-    /**
-     * Announce a message to screen readers by specifying the politeness level
-    */
-    speak: (message: string, politeness?: 'polite' | 'assertive') => void
-
-    /**
-     * Announce a message to screen readers with a polite politeness level
-    */
-    polite: (message: string) => void
-
-    /**
-     * Announce a message to screen readers with an assertive politeness level
-    */
-    assertive: (message: string) => void
-
-    /**
-     * Stop all announcements
-    */
-    stop: () => void
-  }
-
-  interface Log {
-    /**
-    * Log an info message
-    */
-    info(...args): typeof console.info
-    /**
-    * Log an error message
-    */
-    error(...args): typeof console.error
-    /**
-    * Log a warning
-    */
-    warn(...args): typeof console.warn
-    /**
-    * Log a debug message
-    */
-    debug(...args): typeof console.debug
-  }
-  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 PropsArray<T extends string> = T[]
-  type AdvancedProps = AdvancedProp[]
-  type MixedProps<T extends string> = (T | AdvancedProp)[];
-
-  // type ExtractPropNames<T extends Prop[]> = T extends (infer U)[]
-  // ? U extends string
-  //   ? U
-  //   : U extends AdvancedProp
-  //   ? U['key']
-  //   : never
-  // : never;
-
-  type NotFunction<T> = T extends Function ? never : T;
-
-  /**
-   * Internal state of a Component instance
-   */
-  interface State {
-    [key: string]: any
-  }
-
-  interface Computed<S, M, P> {
-    [key: string]: (this: ComponentInstance & S & M & P) => any
-  }
-
-  interface Watch<S, M, P> {
-    [key: string]: (this: ComponentInstance & S & M & P, value: any, oldValue: any) => void
-  }
-
-  interface Methods {
-    [key: string]: (this: ComponentInstance & State & Methods, ...args: any) => any;
-  }
-
-  // interface MethodsExtended<S, M, P> extends Methods {
-  //   [key: string]: (this: ComponentInstance & S & M & P) => any;
-  // }
-
-  interface Input<S, M, P> {
-    [key: string]: ((this: ComponentInstance & S & M & P, event: KeyboardEvent) => void) | undefined,
-
-    /**
-     * Catch all input function
-     *
-     * Will be invoked when there is no dedicated function for a certain key
-    */
-    any?: (this: ComponentInstance & S & M & P, event: KeyboardEvent) => void,
-  }
-
-  interface Log {
-    /**
-    * Log an info message
-    */
-    info(...args): typeof console.info
-    /**
-    * Log an error message
-    */
-    error(...args): typeof console.error
-    /**
-    * Log a warning
-    */
-    warn(...args): typeof console.warn
-    /**
-    * Log a debug message
-    */
-    debug(...args): typeof console.debug
-  }
-
-  interface Hooks<S, M, P> {
-    /**
-    * Fires when the Component is being instantiated.
-    * At this moment child elements will not be available yet
-    */
-    init?: (this: ComponentInstance & S & M & P, ...args: any) => void
-    /**
-    * Fires when the Component is fully initialized and ready for interaction.
-    */
-    ready?: (this: ComponentInstance & S & M & P, ...args: any) => void
-    /**
-    * Triggers when the Component receives focus.
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    focus?: (this: ComponentInstance & S & M & P, ...args: any) => void
-    /**
-    * Triggers when the Component loses focus.
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    unfocus?: (this: ComponentInstance & S & M & P, ...args: any) => void
-    /**
-    * Fires when the Component is being destroyed and removed.
-    */
-    destroy?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-    /**
-    * Fires upon each frame start  (allowing you to tap directly into the renderloop)
-    *
-    * Note: This hook will fire continuously, multiple times per second!
-    */
-    frameTick?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-    /**
-    * Fires when the component enters the viewport _margin_ and is attached to the render tree
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    attach?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-    /**
-    * Fires when the component leaves the viewport _margin_ and is detached from the render tree
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    detach?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-    /**
-    * Fires when the component enters the visible viewport
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    enter?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-    /**
-    * Fires when the component leaves the visible viewport
-    *
-    * This event can fire multiple times during the component's lifecycle
-    */
-    exit?: (this: ComponentInstance & S & M & P, ...args: any) => void,
-  }
-
-  /**
-   * Route object
-  */
-  interface Route {
-    path: string,
-    params: Record<string, string>,
-    options?: {
-      inHistory?: boolean,
-      keepAlive?: boolean,
-      [key: string]: any,
-    },
-    data?: Record<string, any>,
-    component?: (args: { props: any }, holder: any, context: any) => Promise<any>,
-    hooks?: {
-      before?: (route: Route, previousRoute: Route) => Promise<string | Route | void>,
-    }
-  }
-
-
-  interface Router {
-    /**
-     * Navigate to a different location
-    */
-    to(location: string, data?: Record<string, any>, options?: Record<string, any>): void;
-
-    /**
-     * Navigate to the previous location
-    */
-    back(): boolean;
-
-    /**
-     * Get the current route read-only
-    */
-    readonly currentRoute: Route;
-
-    /**
-     * Get the list of all routes
-     */
-    readonly routes: Route[];
-
-    /**
-     * Get navigating state
-     */
-    readonly navigating: boolean;
-
-  }
-
-  export interface ComponentInstance {
-    /**
-    * Listen to events emitted by other components
-    */
-    $listen: {
-      (event: string, callback: (args: any) => void, priority?: number): 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) => ReturnType<typeof setTimeout>
-
-    /**
-    * Clear a timeout
-    */
-    $clearTimeout: (id: ReturnType<typeof setTimeout>) => void
-
-    /**
-    * Set an interval that is automatically cleaned upon component destroy
-    */
-    $setInterval: (callback: (args: any) => void, ms?: number | undefined) => ReturnType<typeof setInterval>
-
-    /**
-    * Clear a interval
-    */
-    $clearInterval: (id: ReturnType<typeof setInterval>) => void
-
-    /**
-    * 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
-    /**
-     * @deprecated
-     * Deprecated:  use `this.$focus()` instead
-     */
-    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
-
-    /**
-     * @deprecated
-     * Deprecated: use `this.$select()` instead
-     */
-    select: (ref: string) => ComponentInstance | ElementInstance
-
-    /**
-     * Announcer methods for screen reader support
-     */
-    $announcer: Announcer
-
-    /**
-     * Triggers a forced update on state variables.
-     */
-    $trigger: (key: string) => void
-    /**
-     * @deprecated
-     *
-     * Triggers a forced update on state variables.
-     * Deprecated: use `this.$trigger()` instead
-     */
-    trigger: (key: string) => void
-
-    /**
-     * Router instance
-     */
-    $router: Router
-
-  }
-
-  export interface ElementInstance {
-    focus?: () => void
-    $focus?: () => void
-  }
-
-  export interface ComponentConfig<Props extends string, S, M> {
-    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: { [K in Props]: any}) => S,
-    /**
-     * 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?: PropsArray<Props> | AdvancedProps | MixedProps<Props>
-    /**
-     * Computed properties
-     */
-    computed?: Computed<S, M, { [K in Props]: any}>,
-    /**
-     * Watchers for changes to state variables, props or computed properties
-     */
-    watch?: Watch<S, M, { [K in Props]: any}>,
-    /**
-     * Hooking into Lifecycle events
-     */
-    hooks?: Hooks<S, M, { [K in Props]: any}>,
-    /**
-     * Methods for abstracting more complex business logic into separate function
-     */
-    methods?: M //MethodsExtended<S, M, { [K in Props]: any}>,
-    /**
-     * Tapping into user input
-     */
-    input?: Input<S, M, { [K in Props]: any}>
-  }
-}
-
-
- /**
- * Blits.Component()
- */
-declare function Component<
-    Props extends string,
-    S extends Component.State,
-    M extends Component.Methods
-  >(
-  name: Component.Name,
-  config: Component.ComponentConfig<Props, S, M>
-) : Component.ComponentInstance
-
-export default Component;

package/src/launch.d.ts

@@ -1,273 +0,0 @@
-/*
- * 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'
-import {type Stage, type ShaderEffect as RendererShaderEffect, type WebGlCoreShader} from '@lightningjs/renderer'
-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 SdfFontWithFile {
-  /**
-    * Location of the font file (i.e. `/fonts/OpenSans-Medium.ttf`)
-    */
-  file: string
-}
-
-interface SdfFontWithPngJson {
-  /**
-  * 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 SdfFont = {
-  /**
-  * Name of the font family
-  */
-  family: string,
-  /**
-  * Type of font (msdf or sdf)
-  */
-  type: 'msdf' | 'sdf',
-} & (SdfFontWithFile | SdfFontWithPngJson)
-
-type Shader = {
-  name: string,
-  type: WebGlCoreShader
-}
-
-type ShaderEffect = {
-  name: string,
-  type: RendererShaderEffect
-}
-
-type ScreenResolutions = 'hd' | '720p' | 720 | 'fhd' | 'fullhd' | '1080p' | 1080 | '4k' | '2160p' | 2160
-
-type Font = WebFont | SdfFont
-
-export type DebugLevel = 0 | 1 | 2
-export type LogTypes = 'info' | 'warn' | 'error' | 'debug'
-export type ReactivityModes = 'Proxy' | 'defineProperty'
-export type RenderModes = 'webgl' | 'canvas'
-
-interface ExtensionLoader {
-  async (stage: Stage): void
-}
-/**
- * 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 | LogTypes[],
-  /**
-   * Fonts to be used in the Application
-   */
-  fonts?: Font[],
-  /**
-   * Effects to be used by DynamicShader
-   */
-  effects?: ShaderEffect[],
-  /**
-   * Shaders to be used in the application
-   */
-  shaders?: Shader[],
-  /**
-   * Default font family to use in the Application when no font attribute is specified
-   * on a Text-component
-   *
-   * The default font must be registered in the `fonts` array in the settings.
-   *
-   * Defaults to `sans-serif` font family, which is the default of the Lightning Renderer
-   */
-  defaultFont?: string,
-  /**
-   * Custom keymapping
-   */
-  keymap?: object,
-  /**
-   * Mode of reactivity (`Proxy` or `defineProperty`)
-   */
-  reactivityMode?: ReactivityModes,
-  /**
-  * Screen resolution of the device, defining the pixelRatio used to convert dimensions
-  * and positions in the App code to the actual device logical coordinates
-  *
-  * If not supplied, Blits will try to autodetect the device screen resolution. Otherwise
-  * the exact dimensions and positions used the app code are used.
-  *
-  * Note: If the option `pixelRatio` is specified in the Settings object, this value will take presedence
-  * over the screen resolution setting.
-  *
-  * Currently 3 screen resolutions are supported, which can be defined with different alias values:
-  *
-  * For 720x1080 (1px = 0.66666667px)
-  * - hd
-  * - 720p
-  * - 720
-  *
-  * For 1080x1920 (1px = 1px)
-  * - fhd
-  * - fullhd
-  * - 1080p
-  * - 1080
-  *
-  * For 2160x3840 (1px = 2px)
-  * - 4k
-  * - 2160p
-  * - 2160
-  */
-  screenResolution?: ScreenResolutions,
-  /**
-  * Custom pixel ratio of the device used to convert dimensions
-  * and positions in the App code to the actual device logical coordinates
-  *
-  * Takes presedence over the `screenResolution` setting
-  *
-  * Defaults to 1 if not specified
-  */
-  pixelRatio?: number
-  /**
-   * Interval in milliseconds to receive FPS updates
-   *
-   * @remarks
-   * If set to `0`, FPS updates will be disabled.
-   *
-   * @defaultValue `1000` (disabled)
-   */
-  fpsInterval?: number
-  /**
-  * Maximum number of web workers to spin up simultaneously for offloading functionality such
-  * as image loading to separate threads (when supported by the browser)
-  *
-  * If not specified defaults to the number of logical processers available as reported by
-  * `navigator.hardwareConcurrency` (or 2 if `navigator.hardwareConcurrency` is not supported)
-  */
-  webWorkersLimit?: number
-  /**
-   * Background color of the canvas (also known as the clearColor)
-   *
-   * Can be a color name (red, blue, silver), a hexadecimal color (`#000000`, `#ccc`),
-   * or a color number in rgba order (`0xff0033ff`)
-   *
-   * Defauls to transparent (`0x00000000`)
-   *
-   */
-  canvasColor?: string,
-  /**
-   * Enable inspector
-   *
-   * Enables the inspector tool for debugging and inspecting the application, the node tree
-   * will be replicated in the DOM and can be inspected using the browser's developer tools
-   *
-   * Defaults to `false`
-   */
-  inspector?: boolean,
-  /**
-   * Add an extra margin to the viewport for earlier pre-loading of elements and components
-   *
-   * By default the Lightning renderer, only renders elements that are inside the defined viewport.
-   * Everything outside of these bounds is removed from the render tree.
-   *
-   * With the viewportMargin you have the option to _virtually_ increase the viewport area,
-   * to expedite the pre-loading of elements and / or delay the unloading of elements depending
-   * on their position in the (virtual) viewport
-   *
-   * The margin can be specified in 4 directions by defining an array [top, right, bottom, left],
-   * or as a single number which is then applied to all 4 directions equally.
-   *
-   * Defaults to `0`
-   */
-  viewportMargin?: number | [number, number, number, number],
-  /**
-   * Threshold in `Megabytes` after which all the textures that are currently not visible
-   * within the configured viewport margin will be be freed and cleaned up
-   *
-   * When passed `0` the threshold is disabled and textures will not be actively freed
-   * and cleaned up
-   *
-   * Defaults to `200` (mb)
-   */
-  gpuMemoryLimit?: number,
-  /**
-   * Defines which mode the renderer should operate in: `webgl` or `canvas`
-   *
-   * SDF fonts are not supported in _canvas_ renderMode. Instead, _web_ fonts should
-   * be used. Also note that Canvas2d rendering doesnt support the use of shaders.
-   *
-   * Defaults to `webgl`
-   */
-  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
-}
-
-/**
- * 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;