@playcanvas/web-components 0.11.0 → 0.11.1

package/src/components/script.ts

@@ -1,4 +1,4 @@
-import { Script } from 'playcanvas';
+import type { Script } from 'playcanvas';
 
 import { AsyncElement } from '../async-element';
 import { parseBool } from '../parse';
@@ -39,18 +39,11 @@ import { parseBool } from '../parse';
 class ScriptElement extends AsyncElement {
     private _attributes: Record<string, any> = {};
 
-    private _enabled: boolean = true;
-
-    /**
-     * Whether readiness has been signalled. Creation can happen more than once over an
-     * element's life (a runtime `name` change recreates the instance), but `ready` is a
-     * one-shot signal, so only the first successful creation fires it.
-     */
-    private _readySignalled: boolean = false;
+    private _enabled = true;
 
     /**
      * The Script instance created for this element by its parent `<pc-scripts>` element.
-     * @ignore
+     * @internal
      */
     _script: Script | null = null;
 
@@ -64,10 +57,12 @@ class ScriptElement extends AsyncElement {
      */
     set scriptAttributes(value: Record<string, any>) {
         this._attributes = value ?? {};
-        this.dispatchEvent(new CustomEvent('scriptattributeschange', {
-            detail: { attributes: this._attributes },
-            bubbles: true
-        }));
+        this.dispatchEvent(
+            new CustomEvent('scriptattributeschange', {
+                detail: { attributes: this._attributes },
+                bubbles: true
+            })
+        );
     }
 
     /**
@@ -84,10 +79,12 @@ class ScriptElement extends AsyncElement {
      */
     set enabled(value: boolean) {
         this._enabled = value;
-        this.dispatchEvent(new CustomEvent('scriptenablechange', {
-            detail: { enabled: value },
-            bubbles: true
-        }));
+        this.dispatchEvent(
+            new CustomEvent('scriptenablechange', {
+                detail: { enabled: value },
+                bubbles: true
+            })
+        );
     }
 
     /**
@@ -137,17 +134,27 @@ class ScriptElement extends AsyncElement {
         // Script instances are created by the parent pc-scripts element, so an element placed
         // anywhere else is inert and never becomes ready - warn rather than hang silently
         if (this.parentElement?.tagName !== 'PC-SCRIPTS') {
-            console.warn(`pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`);
+            console.warn(
+                `pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`
+            );
         }
     }
 
+    disconnectedCallback() {
+        // Re-arm readiness so a re-inserted element announces the instance created for it then.
+        // `_script` is deliberately NOT cleared here: the parent's mutation observer processes
+        // this removal afterwards and reads it to establish which engine script this element
+        // owned - the parent is what clears it.
+        this._resetReady();
+    }
+
     /**
      * Called by the parent `<pc-scripts>` element when the script instance has been created.
-     * @ignore
+     * Creation can happen more than once per connection (a runtime `name` change recreates the
+     * instance), but `_onReady` signals readiness at most once per cycle.
+     * @internal
      */
     _onScriptCreated() {
-        if (this._readySignalled) return;
-        this._readySignalled = true;
         this._onReady();
     }
 
@@ -165,7 +172,9 @@ class ScriptElement extends AsyncElement {
                 try {
                     this.scriptAttributes = JSON.parse(newValue);
                 } catch (error) {
-                    console.warn(`Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`);
+                    console.warn(
+                        `Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`
+                    );
                 }
                 break;
             case 'enabled':
@@ -176,10 +185,12 @@ class ScriptElement extends AsyncElement {
                 // the added-node mutation), so only a genuine rename is signalled here. Note
                 // that setAttribute fires this callback even when the value is unchanged.
                 if (oldValue !== null && oldValue !== newValue) {
-                    this.dispatchEvent(new CustomEvent('scriptnamechange', {
-                        detail: { oldName: oldValue, newName: newValue },
-                        bubbles: true
-                    }));
+                    this.dispatchEvent(
+                        new CustomEvent('scriptnamechange', {
+                            detail: { oldName: oldValue, newName: newValue },
+                            bubbles: true
+                        })
+                    );
                 }
                 break;
         }
@@ -188,10 +199,4 @@ class ScriptElement extends AsyncElement {
 
 customElements.define('pc-script', ScriptElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-script': ScriptElement;
-    }
-}
-
 export { ScriptElement };

package/src/components/scrollbar-component.ts

@@ -1,8 +1,10 @@
-import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL, ScrollbarComponent } from 'playcanvas';
+import type { ScrollbarComponent } from 'playcanvas';
+import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { getEntity, parseEnum, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 const orientations = new Map<'horizontal' | 'vertical', number>([
     ['horizontal', ORIENTATION_HORIZONTAL],
     ['vertical', ORIENTATION_VERTICAL]
@@ -30,7 +32,7 @@ class ScrollbarComponentElement extends ComponentElement {
         super('scrollbar');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             orientation: orientations.get(this._orientation),
             value: this._value,
@@ -133,13 +135,7 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [
-            ...super.observedAttributes,
-            'orientation',
-            'value',
-            'handle-size',
-            'handle'
-        ];
+        return [...super.observedAttributes, 'orientation', 'value', 'handle-size', 'handle'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -164,10 +160,4 @@ class ScrollbarComponentElement extends ComponentElement {
 
 customElements.define('pc-scrollbar', ScrollbarComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-scrollbar': ScrollbarComponentElement;
-    }
-}
-
 export { ScrollbarComponentElement };

package/src/components/scrollview-component.ts

@@ -1,8 +1,17 @@
-import { SCROLL_MODE_BOUNCE, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, ScrollViewComponent, Vec2 } from 'playcanvas';
+import type { ScrollViewComponent } from 'playcanvas';
+import {
+    SCROLL_MODE_BOUNCE,
+    SCROLL_MODE_CLAMP,
+    SCROLL_MODE_INFINITE,
+    SCROLLBAR_VISIBILITY_SHOW_ALWAYS,
+    SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED,
+    Vec2
+} from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const scrollModes = new Map<'clamp' | 'bounce' | 'infinite', number>([
     ['clamp', SCROLL_MODE_CLAMP],
     ['bounce', SCROLL_MODE_BOUNCE],
@@ -54,7 +63,7 @@ class ScrollViewComponentElement extends ComponentElement {
         super('scrollview');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             horizontal: this._horizontal,
             vertical: this._vertical,
@@ -244,7 +253,8 @@ class ScrollViewComponentElement extends ComponentElement {
     set horizontalScrollbarVisibility(value: 'always' | 'when-required') {
         this._horizontalScrollbarVisibility = value;
         if (this.component) {
-            this.component.horizontalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+            this.component.horizontalScrollbarVisibility =
+                visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -264,7 +274,8 @@ class ScrollViewComponentElement extends ComponentElement {
     set verticalScrollbarVisibility(value: 'always' | 'when-required') {
         this._verticalScrollbarVisibility = value;
         if (this.component) {
-            this.component.verticalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+            this.component.verticalScrollbarVisibility =
+                visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -428,10 +439,4 @@ class ScrollViewComponentElement extends ComponentElement {
 
 customElements.define('pc-scrollview', ScrollViewComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-scrollview': ScrollViewComponentElement;
-    }
-}
-
 export { ScrollViewComponentElement };

package/src/components/sound-component.ts

@@ -1,8 +1,9 @@
-import { SoundComponent } from 'playcanvas';
+import type { SoundComponent } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseEnum, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The SoundComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sounds/ | `<pc-sounds>`} elements.
@@ -14,24 +15,24 @@ import { parseBool, parseEnum, parseNumber } from '../parse';
 class SoundComponentElement extends ComponentElement {
     private _distanceModel: 'exponential' | 'inverse' | 'linear' = 'linear';
 
-    private _maxDistance: number = 10000;
+    private _maxDistance = 10000;
 
-    private _pitch: number = 1;
+    private _pitch = 1;
 
-    private _positional: boolean = false;
+    private _positional = false;
 
-    private _refDistance: number = 1;
+    private _refDistance = 1;
 
-    private _rollOffFactor: number = 1;
+    private _rollOffFactor = 1;
 
-    private _volume: number = 1;
+    private _volume = 1;
 
     /** @ignore */
     constructor() {
         super('sound');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             distanceModel: this._distanceModel,
             maxDistance: this._maxDistance,
@@ -228,10 +229,4 @@ class SoundComponentElement extends ComponentElement {
 
 customElements.define('pc-sounds', SoundComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-sounds': SoundComponentElement;
-    }
-}
-
 export { SoundComponentElement };

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,4 +1,5 @@
-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';
@@ -62,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.
@@ -92,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.
@@ -128,8 +136,10 @@ class EntityElement extends AsyncElement {
 
     /**
      * 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.
+     * 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.
      */
@@ -138,9 +148,19 @@ class EntityElement extends AsyncElement {
         this._appElement = null;
         this._entity = null;
         this._built = false;
+        this._resetReady();
     }
 
-    buildHierarchy(app: AppBase) {
+    /**
+     * 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;
 
@@ -168,19 +188,19 @@ 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);
             });
         }
     }
@@ -392,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')) {
@@ -400,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'
+                }
+            );
         }
     }