@playcanvas/web-components 0.11.0 → 0.11.1

package/src/material.ts

@@ -21,17 +21,26 @@ import {
     SPECOCC_GLOSSDEPENDENT,
     SPECOCC_NONE,
     StandardMaterial,
-    Vec2,
-    type EventHandle,
-    type Texture
+    Vec2
 } from 'playcanvas';
+import type { EventHandle, Texture } from 'playcanvas';
 
-import { AppElement } from './app';
+import type { AppElement } from './app';
 import { AssetElement } from './asset';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2 } from './parse';
 
-type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' |
-    'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
+type BlendType =
+    | 'none'
+    | 'normal'
+    | 'additive'
+    | 'additive-alpha'
+    | 'premultiplied'
+    | 'multiplicative'
+    | 'multiplicative-2x'
+    | 'screen'
+    | 'min'
+    | 'max'
+    | 'subtractive';
 
 const blendTypes = new Map<BlendType, number>([
     ['none', BLEND_NONE],
@@ -100,8 +109,8 @@ const roughnessAliases = ['roughness', 'roughness-map'];
  * The texture slots a `pc-material` can populate. Each is backed by a `pc-asset` id rather than a
  * `Texture`, so the element can be authored before the asset has loaded.
  */
-type TextureSlot = 'aoMap' | 'diffuseMap' | 'emissiveMap' | 'glossMap' | 'heightMap' |
-    'metalnessMap' | 'normalMap' | 'opacityMap';
+type TextureSlot =
+    'aoMap' | 'diffuseMap' | 'emissiveMap' | 'glossMap' | 'heightMap' | 'metalnessMap' | 'normalMap' | 'opacityMap';
 
 /**
  * The MaterialElement interface provides properties and methods for manipulating
@@ -286,7 +295,7 @@ class MaterialElement extends HTMLElement {
 
     private _useLighting = true;
 
-    // Diverges from the engine default of false - see the class docblock and createMaterial()
+    // Diverges from the engine default of false - see the class docblock and _createMaterial()
     private _useMetalness = true;
 
     private _useMetalnessSpecularColor = false;
@@ -306,10 +315,14 @@ class MaterialElement extends HTMLElement {
 
     private _glossConflictWarned = false;
 
+    /**
+     * The material. `null` until the containing application has created it — an element present
+     * at startup has its material once the application is ready.
+     */
     material: StandardMaterial | null = null;
 
     async connectedCallback() {
-        const appElement = this.parentElement?.closest('pc-app') as AppElement | null ?? null;
+        const appElement = (this.parentElement?.closest('pc-app') as AppElement | null) ?? null;
 
         // Materials must be direct children of pc-app (matches the boot query ':scope > pc-material')
         if (!appElement || this.parentElement !== appElement) {
@@ -326,11 +339,18 @@ class MaterialElement extends HTMLElement {
         // elements inserted (or re-inserted) after the app is already running
         if (!this.material) {
             if (!appElement.app) return; // pc-app is re-connecting; its own boot will create this
-            this.createMaterial();
+            this._createMaterial();
         }
     }
 
-    createMaterial() {
+    /**
+     * Creates the material from the element's cached properties. Called by the containing
+     * `<pc-app>` element during its boot sweep, and on connection for elements inserted while
+     * the application is already running.
+     *
+     * @internal
+     */
+    _createMaterial() {
         const material = new StandardMaterial();
         this.material = material;
 
@@ -464,10 +484,10 @@ class MaterialElement extends HTMLElement {
      * warning latches and reports once per episode, clearing when the clash is resolved.
      */
     private _warnGlossConflict() {
-        const quote = (names: string[]) => `'${names.join('\', \'')}'`;
+        const quote = (names: string[]) => `'${names.join("', '")}'`;
 
-        const roughness = roughnessAliases.filter(name => this.hasAttribute(name));
-        const gloss = glossConflicts.filter(name => this.hasAttribute(name));
+        const roughness = roughnessAliases.filter((name) => this.hasAttribute(name));
+        const gloss = glossConflicts.filter((name) => this.hasAttribute(name));
 
         if (roughness.length === 0 || gloss.length === 0) {
             this._glossConflictWarned = false;
@@ -477,8 +497,10 @@ class MaterialElement extends HTMLElement {
         if (this._glossConflictWarned) return;
         this._glossConflictWarned = true;
 
-        console.warn(`pc-material '${this.id}' sets both ${quote(roughness)} and ${quote(gloss)} - ` +
-            'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.');
+        console.warn(
+            `pc-material '${this.id}' sets both ${quote(roughness)} and ${quote(gloss)} - ` +
+                'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.'
+        );
     }
 
     /**
@@ -488,7 +510,7 @@ class MaterialElement extends HTMLElement {
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.
      */
-    setMap(id: string, slot: TextureSlot) {
+    private _setMap(id: string, slot: TextureSlot) {
         // Drop any load still pending for this slot - its texture is no longer the one we want
         this._mapHandles.get(slot)?.off();
         this._mapHandles.delete(slot);
@@ -509,10 +531,13 @@ class MaterialElement extends HTMLElement {
             return;
         }
 
-        this._mapHandles.set(slot, asset.once('load', () => {
-            this._mapHandles.delete(slot);
-            this._applyMap(slot, asset.resource as Texture);
-        }));
+        this._mapHandles.set(
+            slot,
+            asset.once('load', () => {
+                this._mapHandles.delete(slot);
+                this._applyMap(slot, asset.resource as Texture);
+            })
+        );
     }
 
     /**
@@ -592,7 +617,7 @@ class MaterialElement extends HTMLElement {
      */
     set aoMap(value: string) {
         this._aoMap = value;
-        this.setMap(value, 'aoMap');
+        this._setMap(value, 'aoMap');
     }
 
     /**
@@ -850,7 +875,7 @@ class MaterialElement extends HTMLElement {
      */
     set diffuseMap(value: string) {
         this._diffuseMap = value;
-        this.setMap(value, 'diffuseMap');
+        this._setMap(value, 'diffuseMap');
     }
 
     /**
@@ -1007,7 +1032,7 @@ class MaterialElement extends HTMLElement {
      */
     set emissiveMap(value: string) {
         this._emissiveMap = value;
-        this.setMap(value, 'emissiveMap');
+        this._setMap(value, 'emissiveMap');
     }
 
     /**
@@ -1205,7 +1230,7 @@ class MaterialElement extends HTMLElement {
      */
     set glossMap(value: string) {
         this._glossMap = value;
-        this.setMap(value, 'glossMap');
+        this._setMap(value, 'glossMap');
     }
 
     /**
@@ -1322,7 +1347,7 @@ class MaterialElement extends HTMLElement {
      */
     set heightMap(value: string) {
         this._heightMap = value;
-        this.setMap(value, 'heightMap');
+        this._setMap(value, 'heightMap');
     }
 
     /**
@@ -1479,7 +1504,7 @@ class MaterialElement extends HTMLElement {
      */
     set metalnessMap(value: string) {
         this._metalnessMap = value;
-        this.setMap(value, 'metalnessMap');
+        this._setMap(value, 'metalnessMap');
     }
 
     /**
@@ -1596,7 +1621,7 @@ class MaterialElement extends HTMLElement {
      */
     set normalMap(value: string) {
         this._normalMap = value;
-        this.setMap(value, 'normalMap');
+        this._setMap(value, 'normalMap');
     }
 
     /**
@@ -1694,7 +1719,7 @@ class MaterialElement extends HTMLElement {
     set occludeDirect(value: boolean) {
         this._occludeDirect = value;
         if (this.material) {
-            // @ts-ignore see createMaterial() - the engine mistypes occludeDirect as a number
+            // @ts-ignore see _createMaterial() - the engine mistypes occludeDirect as a number
             this.material.occludeDirect = value;
             this._scheduleUpdate();
         }
@@ -1796,7 +1821,7 @@ class MaterialElement extends HTMLElement {
      */
     set opacityMap(value: string) {
         this._opacityMap = value;
-        this.setMap(value, 'opacityMap');
+        this._setMap(value, 'opacityMap');
     }
 
     /**
@@ -2150,6 +2175,13 @@ class MaterialElement extends HTMLElement {
         return this._useTonemap;
     }
 
+    /**
+     * Returns the {@link StandardMaterial} created by the `<pc-material>` element with the given
+     * `id`, or `undefined` if there is no such element or its material has not been created yet.
+     *
+     * @param id - The `id` of the `<pc-material>` element.
+     * @returns The material, or `undefined`.
+     */
     static get(id: string) {
         const materialElement = document.querySelector<MaterialElement>(`pc-material[id="${id}"]`);
         return materialElement?.material;
@@ -2508,10 +2540,4 @@ class MaterialElement extends HTMLElement {
 
 customElements.define('pc-material', MaterialElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-material': MaterialElement;
-    }
-}
-
 export { MaterialElement };

package/src/model.ts

@@ -1,4 +1,4 @@
-import { ContainerResource, Entity } from 'playcanvas';
+import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
@@ -10,39 +10,83 @@ import { AsyncElement } from './async-element';
  * {@link HTMLElement} interface.
  */
 class ModelElement extends AsyncElement {
-    private _asset: string = '';
+    private _asset = '';
 
     private _entity: Entity | null = null;
 
+    /**
+     * Incremented on every new load and on disconnect, and captured by a load when it starts. A
+     * load that resumes from an await or a load callback abandons itself if the value has moved
+     * on, so a superseded load can neither instantiate a second entity nor parent one that has
+     * since been destroyed.
+     */
+    private _loadGeneration = 0;
+
+    /**
+     * The pending asset-load subscription of the current load, if it is waiting for its asset.
+     * Held so that whatever supersedes the load can detach the handler from the asset, rather
+     * than leave it registered until the asset loads (or forever, if it never does).
+     */
+    private _loadHandle: EventHandle | null = null;
+
+    /**
+     * The root entity of the instantiated model. `null` until the container asset has loaded
+     * and been instantiated, and again once the element has been removed from the document.
+     * @returns The model's root entity, or `null`.
+     */
+    get entity(): Entity | null {
+        return this._entity;
+    }
+
     connectedCallback() {
         this._loadModel();
         this._onReady();
     }
 
     disconnectedCallback() {
+        this._loadGeneration++;
+        this._detachLoadHandler();
         this._unloadModel();
+        this._resetReady();
+    }
+
+    private _detachLoadHandler() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
     }
 
     private _instantiate(container: ContainerResource) {
-        this._entity = container.instantiateRenderEntity();
+        const generation = this._loadGeneration;
+
+        const entity = container.instantiateRenderEntity();
+        this._entity = entity;
 
         // @ts-ignore
         if (container.animations.length > 0) {
-            this._entity.addComponent('anim');
+            entity.addComponent('anim');
             // @ts-ignore
-            this._entity.anim.assignAnimation('animation', container.animations[0].resource);
+            entity.anim.assignAnimation('animation', container.animations[0].resource);
         }
 
+        // The parent's readiness re-arms when it is torn down, so these can resume in a later
+        // connection cycle. The entity is captured above and the generation re-checked, so a
+        // stale resume cannot parent an entity a newer cycle has already destroyed.
         const parentEntityElement = this.closestEntity;
         if (parentEntityElement) {
             parentEntityElement.ready().then(() => {
-                parentEntityElement.entity!.addChild(this._entity!);
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                parentEntityElement.entity!.addChild(entity);
             });
         } else {
             const appElement = this.closestApp;
             if (appElement) {
                 appElement.ready().then(() => {
-                    appElement.app!.root.addChild(this._entity!);
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    appElement.app!.root.addChild(entity);
                 });
             }
         }
@@ -51,7 +95,17 @@ class ModelElement extends AsyncElement {
     private async _loadModel() {
         this._unloadModel();
 
+        // Supersede any load already in flight - only the newest load may instantiate
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandler();
+
         const appElement = await this.closestApp?.ready();
+
+        // The element may have been removed, or another load started, while we waited
+        if (generation !== this._loadGeneration) {
+            return;
+        }
+
         const app = appElement?.app;
 
         const asset = AssetElement.get(this._asset);
@@ -62,7 +116,14 @@ class ModelElement extends AsyncElement {
         if (asset.loaded) {
             this._instantiate(asset.resource as ContainerResource);
         } else {
-            asset.once('load', () => {
+            // The generation is re-checked even though a superseded handler is detached: the
+            // detach relies on how the engine's event emitter treats removal, while the check
+            // holds on its own.
+            this._loadHandle = asset.once('load', () => {
+                this._loadHandle = null;
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
                 this._instantiate(asset.resource as ContainerResource);
             });
             app!.assets.load(asset);
@@ -108,10 +169,4 @@ class ModelElement extends AsyncElement {
 
 customElements.define('pc-model', ModelElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-model': ModelElement;
-    }
-}
-
 export { ModelElement };

package/src/module.ts

@@ -43,17 +43,18 @@ class ModuleElement extends HTMLElement {
         }
     }
 
-    public getLoadPromise(): Promise<void> {
+    /**
+     * Returns the promise that settles when the module has loaded. Awaited by the containing
+     * `<pc-app>` element before it creates its graphics device.
+     *
+     * @returns The load promise.
+     * @internal
+     */
+    _getLoadPromise(): Promise<void> {
         return this.loadPromise;
     }
 }
 
 customElements.define('pc-module', ModuleElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-module': ModuleElement;
-    }
-}
-
 export { ModuleElement };

package/src/parse.ts

@@ -16,7 +16,8 @@
  * literal, and returns `null` instead of falling back to a default.
  */
 
-import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+import type { Entity } from 'playcanvas';
+import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { CSS_COLORS } from './colors';
 
@@ -31,7 +32,7 @@ import { CSS_COLORS } from './colors';
  */
 export const parseComponents = (value: string, count: number): number[] | null => {
     const components = value.trim().split(/\s+/).map(Number);
-    if (components.length !== count || components.some(component => !Number.isFinite(component))) {
+    if (components.length !== count || components.some((component) => !Number.isFinite(component))) {
         return null;
     }
     return components;
@@ -77,7 +78,11 @@ export const parseBool = (value: string | null, defaultValue: boolean): boolean
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Color object.
  */
-export const parseColor = <T extends Color | null>(value: string | null, defaultValue: T, attribute: string): Color | T => {
+export const parseColor = <T extends Color | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Color | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
@@ -92,7 +97,10 @@ export const parseColor = <T extends Color | null>(value: string | null, default
     if (/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
         let hex = value.slice(1);
         if (hex.length === 3 || hex.length === 4) {
-            hex = hex.split('').map(char => char + char).join('');
+            hex = hex
+                .split('')
+                .map((char) => char + char)
+                .join('');
         }
         return new Color().fromString(`#${hex}`);
     }
@@ -103,7 +111,9 @@ export const parseColor = <T extends Color | null>(value: string | null, default
         return new Color(components);
     }
 
-    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`);
+    console.warn(
+        `Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`
+    );
     return cloneDefault(defaultValue);
 };
 
@@ -133,7 +143,9 @@ export const parseEnum = <T extends string>(
     if (names.includes(value as T)) {
         return value as T;
     }
-    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
+    console.warn(
+        `Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`
+    );
     return defaultValue;
 };
 
@@ -147,13 +159,19 @@ export const parseEnum = <T extends string>(
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed number.
  */
-export const parseNumber = <T extends number | null>(value: string | null, defaultValue: T, attribute: string): number | T => {
+export const parseNumber = <T extends number | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): number | T => {
     if (value === null) {
         return defaultValue;
     }
     const number = value.trim() === '' ? NaN : Number(value);
     if (!Number.isFinite(number)) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`
+        );
         return defaultValue;
     }
     return number;
@@ -170,13 +188,19 @@ export const parseNumber = <T extends number | null>(value: string | null, defau
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Quat object.
  */
-export const parseQuat = <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string): Quat | T => {
+export const parseQuat = <T extends Quat | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Quat | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 3);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Quat().setFromEulerAngles(components[0], components[1], components[2]);
@@ -200,7 +224,10 @@ export const parseTags = (value: string | null, defaultValue: string[] = []): st
         // caller's default, or a later mutation would write back through it.
         return [...defaultValue];
     }
-    return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+    return value
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter((tag) => tag !== '');
 };
 
 /**
@@ -213,13 +240,19 @@ export const parseTags = (value: string | null, defaultValue: string[] = []): st
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec2 object.
  */
-export const parseVec2 = <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string): Vec2 | T => {
+export const parseVec2 = <T extends Vec2 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec2 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 2);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 2 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 2 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec2(components);
@@ -235,13 +268,19 @@ export const parseVec2 = <T extends Vec2 | null>(value: string | null, defaultVa
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec3 object.
  */
-export const parseVec3 = <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string): Vec3 | T => {
+export const parseVec3 = <T extends Vec3 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec3 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 3);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec3(components);
@@ -257,13 +296,19 @@ export const parseVec3 = <T extends Vec3 | null>(value: string | null, defaultVa
  * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec4 object.
  */
-export const parseVec4 = <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string): Vec4 | T => {
+export const parseVec4 = <T extends Vec4 | null>(
+    value: string | null,
+    defaultValue: T,
+    attribute: string
+): Vec4 | T => {
     if (value === null) {
         return cloneDefault(defaultValue);
     }
     const components = parseComponents(value, 4);
     if (!components) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 4 space-separated numbers. Using '${defaultValue}'.`);
+        console.warn(
+            `Invalid value '${value}' for attribute '${attribute}'. Expected 4 space-separated numbers. Using '${defaultValue}'.`
+        );
         return cloneDefault(defaultValue);
     }
     return new Vec4(components);

package/src/scene.ts

@@ -1,4 +1,5 @@
-import { Color, Scene, Vec3 } from 'playcanvas';
+import type { Scene } from 'playcanvas';
+import { Color, Vec3 } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
 import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
@@ -77,12 +78,20 @@ class SceneElement extends AsyncElement {
         }
 
         this._scene = app.scene;
-        this.updateSceneSettings();
+        this._updateSceneSettings();
 
         this._onReady();
     }
 
-    updateSceneSettings() {
+    disconnectedCallback() {
+        // The scene belongs to the application, and removing this element - or the <pc-app>
+        // above it, which disconnects first - parts the two. Re-arm readiness so a re-inserted
+        // element announces the scene it acquires then, not the one it lost here.
+        this._scene = null;
+        this._resetReady();
+    }
+
+    private _updateSceneSettings() {
         if (this._scene) {
             this._scene.fog.type = this._fog;
             this._scene.fog.color = this._fogColor;
@@ -251,10 +260,4 @@ class SceneElement extends AsyncElement {
 
 customElements.define('pc-scene', SceneElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-scene': SceneElement;
-    }
-}
-
 export { SceneElement };