@playcanvas/web-components 0.10.1 → 0.11.1

package/src/components/sound-slot.ts

@@ -1,33 +1,34 @@
-import { SoundSlot } from 'playcanvas';
+import type { SoundSlot } from 'playcanvas';
 
 import { AssetElement } from '../asset';
 import { AsyncElement } from '../async-element';
-import { SoundComponentElement } from './sound-component';
 import { parseBool, parseNumber } from '../parse';
 
+import { SoundComponentElement } from './sound-component';
+
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
  * `<pc-sound>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
  */
 class SoundSlotElement extends AsyncElement {
-    private _asset: string = '';
+    private _asset = '';
 
-    private _autoPlay: boolean = false;
+    private _autoPlay = false;
 
     private _duration: number | null = null;
 
-    private _loop: boolean = false;
+    private _loop = false;
 
-    private _name: string = '';
+    private _name = '';
 
-    private _overlap: boolean = false;
+    private _overlap = false;
 
-    private _pitch: number = 1;
+    private _pitch = 1;
 
-    private _startTime: number = 0;
+    private _startTime = 0;
 
-    private _volume: number = 1;
+    private _volume = 1;
 
     /**
      * The `<pc-sounds>` this slot was added to, captured at connect time.
@@ -38,20 +39,31 @@ class SoundSlotElement extends AsyncElement {
      */
     private _soundElement: SoundComponentElement | null = null;
 
+    /**
+     * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
+     * a resume from an await abandons itself if the value has moved on, so a stale callback can
+     * neither act on a torn-down tree nor add its slot alongside a re-inserted element's own
+     * callback.
+     */
+    private _connectionGeneration = 0;
+
     /**
      * The sound slot.
      */
     soundSlot: SoundSlot | null = null;
 
     async connectedCallback() {
+        const generation = ++this._connectionGeneration;
+
         const soundElement = this.soundElement;
         await soundElement?.ready();
 
-        // The element may have been removed, or its parent torn down, while we were waiting. A
-        // <pc-app> disconnects before its children, so by the time we resume the component can
-        // already be gone - see the matching guard in disconnectedCallback below.
+        // The element may have been removed (perhaps re-inserted, which runs a callback of its
+        // own), or its parent torn down, while we were waiting. A <pc-app> disconnects before
+        // its children, so by the time we resume the component can already be gone - see the
+        // matching guard in disconnectedCallback below.
         const component = soundElement?.component;
-        if (!this.isConnected || !component) {
+        if (generation !== this._connectionGeneration || !component) {
             return;
         }
 
@@ -78,12 +90,16 @@ class SoundSlotElement extends AsyncElement {
     }
 
     disconnectedCallback() {
+        // Invalidate any connectedCallback still suspended on an await
+        this._connectionGeneration++;
+
         // Uses the cached parent rather than a fresh lookup, since parentElement is already null
         // by now. The component itself is null if the parent <pc-sound> (or the whole <pc-app>) is
         // being torn down — parents disconnect first and have already removed the component.
         this._soundElement?.component?.removeSlot(this._name);
         this._soundElement = null;
         this.soundSlot = null;
+        this._resetReady();
     }
 
     protected get soundElement(): SoundComponentElement | null {
@@ -310,10 +326,4 @@ class SoundSlotElement extends AsyncElement {
 
 customElements.define('pc-sound', SoundSlotElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-sound': SoundSlotElement;
-    }
-}
-
 export { SoundSlotElement };

package/src/entity.ts

@@ -1,5 +1,7 @@
-import { AppBase, Entity, Vec3 } from 'playcanvas';
+import type { AppBase } from 'playcanvas';
+import { Entity, Vec3 } from 'playcanvas';
 
+import type { AppElement } from './app';
 import { AsyncElement } from './async-element';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -61,7 +63,7 @@ class EntityElement extends AsyncElement {
     /**
      * The pointer event listeners for the entity.
      */
-    private _listeners: { [key: string]: EventListener[] } = {};
+    private _listeners: Record<string, EventListener[]> = {};
 
     /**
      * The event types for which an inline `onpointer*` attribute is currently present.
@@ -75,6 +77,12 @@ class EntityElement extends AsyncElement {
 
     private _entity: Entity | null = null;
 
+    /**
+     * The application element this entity is registered with, cached at creation time so the
+     * entity can be unregistered even once this element has left the DOM.
+     */
+    private _appElement: AppElement | null = null;
+
     /**
      * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
      * been removed from the document — await {@link whenReady} or the element's `ready()`
@@ -85,7 +93,14 @@ class EntityElement extends AsyncElement {
         return this._entity;
     }
 
-    createEntity(app: AppBase) {
+    /**
+     * Creates the backing entity. Called by the containing `<pc-app>` element during its boot
+     * sweep, and on connection for elements inserted while the application is already running.
+     *
+     * @param app - The application to create the entity in.
+     * @internal
+     */
+    _createEntity(app: AppBase) {
         // Guard against double creation. When a subtree is inserted at runtime (e.g. cloning a
         // `<template>`), an ancestor's connectedCallback eagerly creates descendant entities; the
         // descendants' own connectedCallbacks would otherwise create them a second time.
@@ -108,9 +123,44 @@ class EntityElement extends AsyncElement {
         if (this._tags.length > 0) {
             entity.tags.add(this._tags);
         }
+
+        // Register with the owning application, which joins engine nodes back to elements by
+        // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
+        // for every entity in a destroyed subtree, so the element learns of its entity's death no
+        // matter who causes it: this element, an ancestor, the whole application, or a user
+        // script calling entity.destroy().
+        this._appElement = this.closestApp;
+        this._appElement?._registerEntityElement(entity, this);
+        entity.once('destroy', this._onEntityDestroy, this);
     }
 
-    buildHierarchy(app: AppBase) {
+    /**
+     * Handles the destruction of the backing entity. Resets the element so a later re-insertion
+     * starts clean: `_built` must be cleared alongside `_entity`, or _buildHierarchy would bail
+     * and a re-created entity would never be parented. Readiness is re-armed for the same
+     * reason — with the entity gone, a resolved ready promise would resume its awaiters against
+     * a null `entity`.
+     *
+     * @param entity - The entity that was destroyed.
+     */
+    private _onEntityDestroy(entity: Entity) {
+        this._appElement?._unregisterEntityElement(entity);
+        this._appElement = null;
+        this._entity = null;
+        this._built = false;
+        this._resetReady();
+    }
+
+    /**
+     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` when
+     * there is one, and under the application root otherwise. Called by the containing `<pc-app>`
+     * element once a sweep has created every entity, so a parent's existence never depends on
+     * document order.
+     *
+     * @param app - The application whose root adopts parentless entities.
+     * @internal
+     */
+    _buildHierarchy(app: AppBase) {
         if (!this.entity || this._built) return;
         this._built = true;
 
@@ -138,41 +188,29 @@ class EntityElement extends AsyncElement {
         }
 
         // If app is already running, create entity immediately
-        if (closestApp.hierarchyReady) {
+        if (closestApp._hierarchyReady) {
             const app = closestApp.app!;
 
-            this.createEntity(app);
-            this.buildHierarchy(app);
+            this._createEntity(app);
+            this._buildHierarchy(app);
 
             // Handle any child entities that might exist
             const childEntities = this.querySelectorAll<EntityElement>('pc-entity');
             childEntities.forEach((child) => {
-                child.createEntity(app);
+                child._createEntity(app);
             });
             childEntities.forEach((child) => {
-                child.buildHierarchy(app);
+                child._buildHierarchy(app);
             });
         }
     }
 
     disconnectedCallback() {
-        if (this.entity) {
-            // Notify all children that their entities are about to become invalid. Both fields have
-            // to be reset here, not just _entity: a descendant's own disconnectedCallback runs after
-            // this one and skips its reset behind the `if (this.entity)` guard, because we have
-            // already nulled the entity it tests. Leaving _built set would make buildHierarchy bail
-            // on re-insertion, so the descendant would get a fresh entity that is never parented.
-            const children = this.querySelectorAll<EntityElement>('pc-entity');
-            children.forEach((child) => {
-                child._entity = null;
-                child._built = false;
-            });
-
-            // Destroy the entity
-            this.entity.destroy();
-            this._entity = null;
-            this._built = false;
-        }
+        // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
+        // every entity in it - so _onEntityDestroy resets this element AND every descendant
+        // element before the descendants' own disconnectedCallbacks run. Their entities are null
+        // by then, making this call a no-op for them.
+        this._entity?.destroy();
     }
 
     /**
@@ -374,7 +412,7 @@ class EntityElement extends AsyncElement {
 
     removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions) {
         if (this._listeners[type]) {
-            this._listeners[type] = this._listeners[type].filter(l => l !== listener);
+            this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
         }
         super.removeEventListener(type, listener, options);
         if (type.startsWith('pointer')) {
@@ -382,17 +420,20 @@ class EntityElement extends AsyncElement {
         }
     }
 
-    hasListeners(type: string): boolean {
+    /**
+     * Whether the element has a listener for an event type, registered either with
+     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+     * containing `<pc-app>` element to gate pointer event synthesis.
+     *
+     * @param type - The event type.
+     * @returns Whether a listener is registered.
+     * @internal
+     */
+    _hasListeners(type: string): boolean {
         return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
     }
 }
 
 customElements.define('pc-entity', EntityElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-entity': EntityElement;
-    }
-}
-
 export { EntityElement };

package/src/index.ts

@@ -7,7 +7,7 @@
  * @module EngineWebComponents
  */
 
-/* eslint-disable import/order */
+/* eslint-disable import-x/order */
 
 // Note that order matters here (e.g. pc-entity must be defined before components)
 import { AsyncElement, whenReady } from './async-element';
@@ -40,6 +40,50 @@ import { ModelElement } from './model';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
 
+import type {
+    ScriptAttributesChangeEvent,
+    ScriptEnableChangeEvent,
+    ScriptNameChangeEvent
+} from './components/script-component';
+
+declare global {
+    interface HTMLElementEventMap {
+        scriptattributeschange: ScriptAttributesChangeEvent;
+        scriptenablechange: ScriptEnableChangeEvent;
+        scriptnamechange: ScriptNameChangeEvent;
+    }
+
+    interface HTMLElementTagNameMap {
+        'pc-app': AppElement;
+        'pc-asset': AssetElement;
+        'pc-button': ButtonComponentElement;
+        'pc-camera': CameraComponentElement;
+        'pc-collision': CollisionComponentElement;
+        'pc-element': ElementComponentElement;
+        'pc-entity': EntityElement;
+        'pc-gsplat': GSplatComponentElement;
+        'pc-layoutchild': LayoutChildComponentElement;
+        'pc-layoutgroup': LayoutGroupComponentElement;
+        'pc-light': LightComponentElement;
+        'pc-listener': ListenerComponentElement;
+        'pc-material': MaterialElement;
+        'pc-model': ModelElement;
+        'pc-module': ModuleElement;
+        'pc-particles': ParticleSystemComponentElement;
+        'pc-render': RenderComponentElement;
+        'pc-rigidbody': RigidBodyComponentElement;
+        'pc-scene': SceneElement;
+        'pc-screen': ScreenComponentElement;
+        'pc-script': ScriptElement;
+        'pc-scripts': ScriptComponentElement;
+        'pc-scrollbar': ScrollbarComponentElement;
+        'pc-scrollview': ScrollViewComponentElement;
+        'pc-sky': SkyElement;
+        'pc-sound': SoundSlotElement;
+        'pc-sounds': SoundComponentElement;
+    }
+}
+
 export {
     AsyncElement,
     ModuleElement,

package/src/loading-bar.ts

@@ -59,14 +59,14 @@ class LoadingBar {
         // aria-valuenow is set, which is what marks a progressbar indeterminate. jsdom has no Web
         // Animations API, so the guard degrades to a static bar there rather than crashing boot.
         if (typeof this._fill.animate === 'function') {
-            this._sweep = this._fill.animate([
-                { transform: 'scaleX(0.25) translateX(-100%)' },
-                { transform: 'scaleX(0.25) translateX(500%)' }
-            ], {
-                duration: 1000,
-                iterations: Infinity,
-                easing: 'ease-in-out'
-            });
+            this._sweep = this._fill.animate(
+                [{ transform: 'scaleX(0.25) translateX(-100%)' }, { transform: 'scaleX(0.25) translateX(500%)' }],
+                {
+                    duration: 1000,
+                    iterations: Infinity,
+                    easing: 'ease-in-out'
+                }
+            );
         }
     }
 

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 };