index.d.ts

// Type definitions for AFRAME 1.2
// Project: https://aframe.io/
// Definitions by: Paul Shannon <https://github.com/devpaul>
//                 Roberto Ritger <https://github.com/bertoritger>
//                 Trygve Wastvedt <https://github.com/twastvedt>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 3.6

/**
 * Extended tests and examples available at https://github.com/devpaul/aframe-experiments.git
 */

import * as anime from 'animejs';
import * as three from 'three';
import * as threeDeprecated from 'three/examples/jsm/deprecated/Geometry';

export type ThreeLib = typeof three;
export type AnimeLib = typeof anime;

export interface ObjectMap<T = any> {
    [key: string]: T;
}

export interface Animation {
    attribute: string;
    begin: string | number;
    delay: number;
    direction: 'alternate' | 'alternateReverse' | 'normal' | 'reverse';
    dur: number;
    easing(): void;
    end: string;
    fill: 'backwards' | 'both' | 'forwards' | 'none';
    from: any; // TODO type
    repeat: number | 'indefinite';
    to: number;
}

export interface ANode extends HTMLElement {
    // Only public APIs added. Many methods intentionally left out.
    // createdCallback
    // attachedCallback
    // attributeChangedCallback
    closestScene(): Scene;
    closest(selector: string): ANode;
    // detachedCallback
    hasLoaded: boolean;
    load(cb?: () => void, childFilter?: (el: Element) => boolean): void;
    // updateMixins
    registerMixin(id: string): void;
    setAttribute(type: string, newValue: any): void;
    unregisterMixin(id: string): void;
    removeMixinListener(id: string): void;
    attachMixinListener(mixin: HTMLElement): void;
    emit(name: string, detail?: any, bubbles?: boolean): void;
    emitter(name: string, detail?: any, bubbles?: boolean): () => void;
}

export interface Behavior {
    tick(): void;
}

export interface Component<T extends object = any, S extends System = System> {
    attrName?: string | undefined;
    data: T;
    dependencies?: string[] | undefined;
    el: Entity;
    id: string;
    initialized: boolean;
    multiple?: boolean | undefined;
    name: string;
    schema: Schema<T>;
    system: S | undefined;
    events?: any;

    init(data?: T): void;
    pause(): void;
    play(): void;
    remove(): void;
    tick?(time: number, timeDelta: number): void;
    tock?(time: number, timeDelta: number, camera: THREE.Camera): void;
    update(oldData: T): void;
    updateSchema?(): void;

    extendSchema(update: Schema): void;
    flushToDOM(): void;
}

export interface ComponentConstructor<T extends object> {
    new (el: Entity, attrValue: string, id: string): T & Component;
    prototype: T & {
        name: string;
        system: System;
        play(): void;
        pause(): void;
    };
}

export interface ComponentDescriptor<T extends Component = Component> {
    Component: ComponentConstructor<T>;
    dependencies: string[] | undefined;
    multiple: boolean | undefined;

    // internal APIs2
    // parse
    // parseAttrValueForCache
    // schema
    // stringify
    // type
}

export interface Coordinate {
    x: number;
    y: number;
    z: number;
}

export interface DefaultComponents {
    position: Component<Coordinate>;
    rotation: Component<Coordinate>;
    scale: Component<Coordinate>;
}

export interface Entity<C = ObjectMap<Component>> extends ANode {
    components: C & DefaultComponents;
    hasLoaded: boolean;
    isPlaying: boolean;
    object3D: THREE.Object3D;
    object3DMap: ObjectMap<THREE.Object3D>;
    sceneEl?: Scene | undefined;

    destroy(): void;
    addState(name: string): void;
    flushToDOM(recursive?: boolean): void;
    /**
     * @deprecated since 0.4.0
     */
    getComputedAttribute(attr: string): Component;
    getDOMAttribute(attr: string): any;
    getObject3D(type: string): THREE.Object3D;
    getOrCreateObject3D(type: string, construct: any): THREE.Object3D;
    is(stateName: string): boolean;
    pause(): void;
    play(): void;
    setObject3D(type: string, obj: THREE.Object3D): void;
    removeAttribute(attr: string, property?: string): void;
    removeObject3D(type: string): void;
    removeState(stateName: string): void;

    // getAttribute specific usages
    getAttribute(type: string): any;
    getAttribute(type: 'position' | 'rotation' | 'scale'): Coordinate;

    // setAttribute specific usages
    setAttribute(attr: string, value: any): void;
    setAttribute(attr: string, property: string, componentAttrValue?: any): void;
    setAttribute(type: 'position' | 'rotation' | 'scale', value: Coordinate): void;

    // addEventListener specific usages
    addEventListener<K extends keyof EntityEventMap>(
        type: K,
        listener: (event: Event & EntityEventMap[K]) => void,
        useCapture?: boolean
    ): void;
    addEventListener(
        type: string,
        listener: EventListenerOrEventListenerObject,
        useCapture?: boolean
    ): void;
}

export type DetailEvent<D> = Event & {
    detail: D;
    target: EventTarget & Entity;
};

export interface EntityEventMap {
    'child-attached': DetailEvent<{ el: Element | Entity }>;
    'child-detached': DetailEvent<{ el: Element | Entity }>;
    componentchanged: DetailEvent<{
        name: string;
        id: string;
    }>;
    componentinitialized: DetailEvent<{
        name: string;
        id: string;
        data: any;
    }>;
    componentremoved: DetailEvent<{
        name: string;
        id: string;
        newData: any;
        oldData: any;
    }>;
    loaded: EventListener;
    pause: EventListener;
    play: EventListener;
    stateadded: DetailEvent<{ state: string }>;
    stateremoved: DetailEvent<{ state: string }>;
    schemachanged: DetailEvent<{ componentName: string }>;
}

export interface Geometry<T = any> {
    data: T;
    name: string;
    geometry: threeDeprecated.Geometry;
    schema: Schema<any>;

    init(data: any): void;
}

export interface GeometryConstructor<T extends object = object> {
    new (): T & Geometry;
}

export interface GeometryDescriptor<T extends Geometry = Geometry> {
    Geometry: GeometryConstructor<T>;
    schema: Schema;
}

export type MultiPropertySchema<T extends object> = {
    [P in keyof T]: SinglePropertySchema<T[P]> | T[P]
};

export type PropertyTypes =
    | 'array'
    | 'asset'
    | 'audio'
    | 'boolean'
    | 'color'
    | 'int'
    | 'map'
    | 'model'
    | 'number'
    | 'selector'
    | 'selectorAll'
    | 'string'
    | 'vec2'
    | 'vec3'
    | 'vec4';

export type SceneEvents = 'enter-vr' | 'exit-vr' | 'loaded' | 'renderstart';

export interface Scene extends Entity {
    behaviors: Behavior[];
    camera: THREE.Camera;
    canvas: HTMLCanvasElement;
    isMobile: boolean;
    object3D: THREE.Scene;
    renderer: THREE.WebGLRenderer;
    renderStarted: boolean;
    effect?: any; // THREE.VREffect
    systems: ObjectMap<System>;
    time: number;

    enterVR(): Promise<void> | void;
    exitVR(): Promise<void> | void;
    reload(): void;

    addEventListener(
        type: string,
        listener: EventListenerOrEventListenerObject,
        useCapture?: boolean
    ): void;
    addEventListener(type: SceneEvents, listener: EventListener, useCapture?: boolean): void;
}

export type Schema<T extends object = object> = SinglePropertySchema<T> | MultiPropertySchema<T>;

export interface SchemaUtils {
    isSingleProperty(schema: Schema): boolean;
    process(schema: Schema): boolean;
}

export interface Shader {
    name: string;
    data: object;
    schema: Schema<this['data']>;
    material: THREE.Material;
    vertexShader: string;
    fragmentShader: string;

    init(data?: this['data']): void;
    tick?(time: number, timeDelta: number): void;
    update(oldData: this['data']): void;
}

export interface ShaderConstructor<T extends object> {
    new (): T;
}

export interface ShaderDescriptor<T extends Shader = Shader> {
    Shader: ShaderConstructor<T>;
    schema: Schema;
}

export interface SinglePropertySchema<T> {
    type?: PropertyTypes | undefined;
    default?: T | undefined;
    parse?(value: string): T;
    stringify?(value: T): string;
}

export interface System<T extends object = any> {
    data: T;
    schema: Schema<T>;
    el: Entity;
    init(): void;
    pause(): void;
    play(): void;
    tick?(t: number, dt: number): void;
}

export interface SystemConstructor<T extends object = object> {
    new (scene: Scene): T & System;
}

export interface Utils {
    coordinates: {
        isCoordinate(value: string): boolean;
        parse(value: string): Coordinate;
        stringify(coord: Coordinate): string;
    };
    entity: {
        getComponentProperty(entity: Entity, componentName: string, delimiter?: string): any;
        setComponentProperty(
            entity: Entity,
            componentName: string,
            value: any,
            delimiter?: string
        ): void;
    };
    device: {
        isWebXRAvailable: boolean;
        checkHeadsetConnected(): boolean;
        checkHasPositionalTracking(): boolean;
        isMobile(): boolean;
        isTablet(): boolean;
        isIOS(): boolean;
        isGearVR(): boolean;
        isOculusGo(): boolean;
        isR7(): boolean;
        isLandscape(): boolean;
        isBrowserEnvironment(): boolean;
        isNodeEnvironment(): boolean;
        PolyfillControls(object3D: THREE.Object3D): void;
    };
    styleParser: {
        parse(value: string): object;
        stringify(data: object): string;
    };
    deepEqual(a: any, b: any): boolean;
    diff(a: object, b: object): object;
    extend(target: object, ...source: object[]): object;
    extendDeep(target: object, ...source: object[]): object;

    throttle(
        tickFunction: () => void,
        minimumInterval: number,
        optionalContext?: {}
    ): (t: number, dt: number) => void;
    throttleTick(
        tickFunction: (t: number, dt: number) => void,
        minimumInterval: number,
        optionalContext?: {}
    ): (t: number, dt: number) => void;
}

// Definitions
// used as mixins to register functions to create classes (newable functions) in A-Frame
export type ComponentDefinition<T extends object = object> = T & Partial<Component> & ThisType<T & Component>;
export type GeometryDefinition<T extends object = object, U = any> = T & Partial<Geometry<U>>;
export type NodeDefinition<T extends object = object> = T & Partial<ANode>;
export interface PrimitiveDefinition {
    defaultComponents?: any; // TODO cleanup type
    deprecated?: boolean | undefined;
    mappings?: any; // TODO cleanup type
    transforms?: any; // TODO cleanup type
}
export interface MinimalShaderDefinition {
    schema: Shader['schema'];
}
export type ShaderDefinition<T extends object = MinimalShaderDefinition & object> = T &
    Partial<Shader>;
export type SystemDefinition<T extends object = object> = T & Partial<System>;

// root export
export interface AFrame {
    AComponent: Component;
    AEntity: Entity;
    ANode: ANode;
    AScene: Scene;

    components: ObjectMap<ComponentDescriptor>;
    geometries: ObjectMap<GeometryDescriptor>;
    primitives: {
        getMeshMixin(): {
            defaultComponents: { material: object };
            mappings: { [key: string]: any }; // TODO improve any type
        };
        primitives: ObjectMap<Entity>;
    };
    scenes: Scene[];
    schema: SchemaUtils;
    shaders: ObjectMap<ShaderDescriptor>;
    systems: ObjectMap<SystemConstructor>;
    THREE: ThreeLib;
    ANIME: AnimeLib;
    utils: Utils;
    version: string;

    registerComponent<T extends object>(
        name: string,
        component: ComponentDefinition<T>
    ): ComponentConstructor<T>;
    registerElement(name: string, element: object): void;
    registerGeometry<T extends object>(
        name: string,
        geometry: GeometryDefinition<T>
    ): GeometryConstructor<T>;
    registerPrimitive(name: string, primitive: PrimitiveDefinition): void;
    registerShader<T extends MinimalShaderDefinition & object>(
        name: string,
        shader: ShaderDefinition<T>
    ): ShaderConstructor<T>;
    registerSystem<T extends object>(
        name: string,
        definition: SystemDefinition<T>
    ): SystemConstructor<T>;
}

// module.exports
export const AComponent: AFrame['AComponent'];
export const AEntity: AFrame['AEntity'];
export const ANode: AFrame['ANode'];
export const AScene: AFrame['AScene'];
export const components: AFrame['components'];
export const geometries: AFrame['geometries'];
export const primitives: AFrame['primitives'];
export const scenes: AFrame['scenes'];
export const schema: AFrame['schema'];
export const shaders: AFrame['shaders'];
export const systems: AFrame['systems'];
export const THREE: AFrame['THREE'];
export const ANIME: AFrame['ANIME'];
export const utils: AFrame['utils'];
export const version: AFrame['version'];
export const registerComponent: AFrame['registerComponent'];
export const registerElement: AFrame['registerElement'];
export const registerGeometry: AFrame['registerGeometry'];
export const registerPrimitive: AFrame['registerPrimitive'];
export const registerShader: AFrame['registerShader'];
export const registerSystem: AFrame['registerSystem'];

// global exports
declare global {
    var hasNativeWebVRImplementation: boolean;

    namespace AFRAME {
        const AComponent: AFrame['AComponent'];
        const AEntity: AFrame['AEntity'];
        const ANode: AFrame['ANode'];
        const AScene: AFrame['AScene'];
        const components: AFrame['components'];
        const geometries: AFrame['geometries'];
        const primitives: AFrame['primitives'];
        const scenes: AFrame['scenes'];
        const schema: AFrame['schema'];
        const shaders: AFrame['shaders'];
        const systems: AFrame['systems'];
        const THREE: AFrame['THREE'];
        const ANIME: AFrame['ANIME'];
        const utils: AFrame['utils'];
        const version: string;

        const registerComponent: AFrame['registerComponent'];
        const registerElement: AFrame['registerElement'];
        const registerGeometry: AFrame['registerGeometry'];
        const registerPrimitive: AFrame['registerPrimitive'];
        const registerShader: AFrame['registerShader'];
        const registerSystem: AFrame['registerSystem'];
    }

    /**
     * Custom elements augment document methods to return custom HTML
     */
    interface Document {
        createElement(tagName: string): Entity;
        querySelector(selectors: 'a-scene'): Scene;
        querySelector(selectors: string): Entity<any>;
        querySelectorAll(selectors: string): NodeListOf<Entity<any> | Element>;
    }

    interface HTMLCollection extends HTMLCollectionBase {
        /**
         * Retrieves a select object or an object from an options collection.
         */
        namedItem(name: string): Element | Entity | null;
        item(index: number): Element | Entity;
        [index: number]: Element | Entity;
    }
}