@playcanvas/web-components 0.11.0 → 0.11.1

package/src/async-element.ts

@@ -1,17 +1,20 @@
-import { AppElement } from './app';
-import { EntityElement } from './entity';
+import type { AppElement } from './app';
+import type { EntityElement } from './entity';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
  *
- * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
- * composed.
+ * @fires {CustomEvent} ready - Fired when the element is fully initialized — once per readiness
+ * cycle, so an element that is torn down and re-initialized (for example by removing and
+ * re-inserting it) fires it again. Bubbles and is composed.
  */
 class AsyncElement extends HTMLElement {
     private _readyPromise: Promise<void>;
 
     private _readyResolve!: () => void;
 
+    private _readyResolved = false;
+
     /** @ignore */
     constructor() {
         super();
@@ -26,7 +29,7 @@ class AsyncElement extends HTMLElement {
      * @returns The closest app element, or `null`.
      */
     get closestApp(): AppElement | null {
-        return this.parentElement?.closest('pc-app') as AppElement | null ?? null;
+        return (this.parentElement?.closest('pc-app') as AppElement | null) ?? null;
     }
 
     /**
@@ -35,22 +38,45 @@ class AsyncElement extends HTMLElement {
      * @returns The closest entity element, or `null`.
      */
     get closestEntity(): EntityElement | null {
-        return this.parentElement?.closest('pc-entity') as EntityElement | null ?? null;
+        return (this.parentElement?.closest('pc-entity') as EntityElement | null) ?? null;
     }
 
     /**
      * Called when the element is fully initialized and ready. Subclasses should call this when
      * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
-     * event.
+     * event. Signals at most once per readiness cycle: a repeat call before {@link _resetReady}
+     * has re-armed the promise does nothing.
      */
     protected _onReady() {
+        if (this._readyResolved) return;
+        this._readyResolved = true;
         this._readyResolve();
         this.dispatchEvent(new CustomEvent('ready', { bubbles: true, composed: true }));
     }
 
+    /**
+     * Returns the ready promise to its pending state. Subclasses should call this when the
+     * resource their readiness announced is torn down (typically from `disconnectedCallback`),
+     * so that a later re-initialization can signal readiness again. Does nothing while the
+     * promise is still pending — an in-flight waiter carries over to the next readiness cycle
+     * rather than being stranded on a promise nothing will ever resolve.
+     */
+    protected _resetReady() {
+        if (!this._readyResolved) return;
+        this._readyResolved = false;
+        this._readyPromise = new Promise<void>((resolve) => {
+            this._readyResolve = resolve;
+        });
+    }
+
     /**
      * Returns a promise that resolves with this element when it's ready. This is the low-level
      * primitive underlying {@link whenReady}, which is the recommended way to wait for elements.
+     *
+     * Readiness tracks the element's current lifecycle: once a ready element is torn down (for
+     * example by removing it from the document), this returns a fresh promise that resolves when
+     * the element is next ready. A promise obtained earlier stays resolved — call this again
+     * after re-inserting an element rather than reusing a promise from before its removal.
      * @returns A promise that resolves with this element when it's ready.
      */
     ready(): Promise<this> {
@@ -63,7 +89,7 @@ class AsyncElement extends HTMLElement {
  * classes extend {@link AsyncElement}).
  */
 type AsyncElementTagName = {
-    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never
+    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never;
 }[keyof HTMLElementTagNameMap];
 
 /**

package/src/components/button-component.ts

@@ -1,9 +1,11 @@
-import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, ButtonComponent, Color, Vec4 } from 'playcanvas';
+import type { ButtonComponent } from 'playcanvas';
+import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
 import { AssetElement } from '../asset';
-import { ComponentElement } from './component';
 import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const transitionModes = new Map<'tint' | 'sprite', number>([
     ['tint', BUTTON_TRANSITION_MODE_TINT],
     ['sprite', BUTTON_TRANSITION_MODE_SPRITE_CHANGE]
@@ -51,7 +53,7 @@ class ButtonComponentElement extends ComponentElement {
         super('button');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             active: this._active,
             hitPadding: this._hitPadding,
@@ -448,10 +450,4 @@ class ButtonComponentElement extends ComponentElement {
 
 customElements.define('pc-button', ButtonComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-button': ButtonComponentElement;
-    }
-}
-
 export { ButtonComponentElement };

package/src/components/camera-component.ts

@@ -1,8 +1,25 @@
-import { CameraComponent, Color, Vec4, GAMMA_NONE, GAMMA_SRGB, PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_NEUTRAL, TONEMAP_ACES2, TONEMAP_ACES, TONEMAP_HEJL, TONEMAP_NONE, XRTYPE_VR } from 'playcanvas';
+import type { CameraComponent } from 'playcanvas';
+import {
+    Color,
+    Vec4,
+    GAMMA_NONE,
+    GAMMA_SRGB,
+    PROJECTION_ORTHOGRAPHIC,
+    PROJECTION_PERSPECTIVE,
+    TONEMAP_LINEAR,
+    TONEMAP_FILMIC,
+    TONEMAP_NEUTRAL,
+    TONEMAP_ACES2,
+    TONEMAP_ACES,
+    TONEMAP_HEJL,
+    TONEMAP_NONE,
+    XRTYPE_VR
+} from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const projections = new Map<'perspective' | 'orthographic', number>([
     ['perspective', PROJECTION_PERSPECTIVE],
     ['orthographic', PROJECTION_ORTHOGRAPHIC]
@@ -68,7 +85,7 @@ class CameraComponentElement extends ComponentElement {
         super('camera');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
@@ -101,7 +118,10 @@ class CameraComponentElement extends ComponentElement {
      * @param type - The type of XR mode to start.
      * @param space - The space to start the camera in.
      */
-    startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer') {
+    startXr(
+        type: 'immersive-ar' | 'immersive-vr',
+        space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'
+    ) {
         if (this.component && this.xrAvailable) {
             this.component.startXr(type, space, {
                 callback: (err: any) => {
@@ -559,10 +579,4 @@ class CameraComponentElement extends ComponentElement {
 
 customElements.define('pc-camera', CameraComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-camera': CameraComponentElement;
-    }
-}
-
 export { CameraComponentElement };

package/src/components/collision-component.ts

@@ -1,8 +1,10 @@
-import { CollisionComponent, Quat, Vec3 } from 'playcanvas';
+import type { CollisionComponent } from 'playcanvas';
+import { Quat, Vec3 } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseEnum, parseNumber, parseQuat, parseVec3 } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The CollisionComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-collision/ | `<pc-collision>`} elements.
@@ -14,17 +16,17 @@ import { parseBool, parseEnum, parseNumber, parseQuat, parseVec3 } from '../pars
 class CollisionComponentElement extends ComponentElement {
     private _angularOffset: Quat = new Quat();
 
-    private _axis: number = 1;
+    private _axis = 1;
 
-    private _convexHull: boolean = false;
+    private _convexHull = false;
 
     private _halfExtents: Vec3 = new Vec3(0.5, 0.5, 0.5);
 
-    private _height: number = 2;
+    private _height = 2;
 
     private _linearOffset: Vec3 = new Vec3();
 
-    private _radius: number = 0.5;
+    private _radius = 0.5;
 
     private _type: 'box' | 'capsule' | 'compound' | 'cone' | 'cylinder' | 'mesh' | 'sphere' = 'box';
 
@@ -33,7 +35,7 @@ class CollisionComponentElement extends ComponentElement {
         super('collision');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             axis: this._axis,
             angularOffset: this._angularOffset,
@@ -143,7 +145,17 @@ class CollisionComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [...super.observedAttributes, 'angular-offset', 'axis', 'convex-hull', 'half-extents', 'height', 'linear-offset', 'radius', 'type'];
+        return [
+            ...super.observedAttributes,
+            'angular-offset',
+            'axis',
+            'convex-hull',
+            'half-extents',
+            'height',
+            'linear-offset',
+            'radius',
+            'type'
+        ];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -172,7 +184,12 @@ class CollisionComponentElement extends ComponentElement {
                 this.radius = parseNumber(newValue, 0.5, name);
                 break;
             case 'type':
-                this.type = parseEnum(newValue, ['box', 'capsule', 'compound', 'cone', 'cylinder', 'mesh', 'sphere'], 'box', name);
+                this.type = parseEnum(
+                    newValue,
+                    ['box', 'capsule', 'compound', 'cone', 'cylinder', 'mesh', 'sphere'],
+                    'box',
+                    name
+                );
                 break;
         }
     }
@@ -180,10 +197,4 @@ class CollisionComponentElement extends ComponentElement {
 
 customElements.define('pc-collision', CollisionComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-collision': CollisionComponentElement;
-    }
-}
-
 export { CollisionComponentElement };

package/src/components/component.ts

@@ -1,6 +1,6 @@
-import { Component } from 'playcanvas';
+import type { Component } from 'playcanvas';
 
-import { AppElement } from '../app';
+import type { AppElement } from '../app';
 import { AsyncElement } from '../async-element';
 import { parseBool } from '../parse';
 
@@ -18,6 +18,15 @@ class ComponentElement extends AsyncElement {
 
     private _appElement: AppElement | null = null;
 
+    /**
+     * Incremented on every connect and disconnect. connectedCallback captures the value on entry
+     * and abandons itself wherever it resumes from an await if the value has moved on — so a
+     * callback whose element was removed cannot act on a torn-down tree, and one whose element
+     * was removed and re-inserted (which runs a callback of its own) cannot add the component a
+     * second time.
+     */
+    private _connectionGeneration = 0;
+
     /**
      * Creates a new ComponentElement instance.
      *
@@ -30,38 +39,78 @@ class ComponentElement extends AsyncElement {
         this._componentName = componentName;
     }
 
-    // Method to be overridden by subclasses to provide initial component data
-    getInitialComponentData() {
+    /**
+     * Returns the data the component is created with. Overridden by subclasses to supply the
+     * initial values of their cached properties.
+     *
+     * @returns The initial component data.
+     */
+    protected getInitialComponentData() {
         return {};
     }
 
-    async addComponent() {
+    private async _addComponent() {
+        const generation = this._connectionGeneration;
+
         const entityElement = this.closestEntity;
         if (!entityElement) {
             // A component can only exist on an entity, so an element placed outside one is inert.
             // It still becomes ready (with a null `component`), so warn rather than fail silently
             const label = this.id ? ` '${this.id}'` : '';
-            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+            console.warn(
+                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`
+            );
             return;
         }
 
         await entityElement.ready();
+
+        // The element may have been removed, or removed and re-inserted, while the entity became
+        // ready — the component belongs to the connection that owns the current generation.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
         // Add the component to the entity
         const data = this.getInitialComponentData();
         this._component = entityElement.entity!.addComponent(this._componentName, data);
     }
 
-    initComponent() {}
+    /**
+     * Configures the newly added component. Overridden by subclasses whose setup goes beyond
+     * the initial data — child-element handling, asset resolution and the like.
+     */
+    protected initComponent() {
+        // optional hook
+    }
 
     async connectedCallback() {
+        const generation = ++this._connectionGeneration;
+
         this._appElement = this.closestApp ?? null;
         await this._appElement?.ready();
-        await this.addComponent();
+
+        // The element may have been removed, or removed and re-inserted, while the application
+        // became ready. A re-insertion runs a connectedCallback of its own, so a stale resume
+        // must not add the component alongside it.
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
+        await this._addComponent();
+
+        if (generation !== this._connectionGeneration) {
+            return;
+        }
+
         this.initComponent();
         this._onReady();
     }
 
     disconnectedCallback() {
+        // Invalidate any connectedCallback still suspended on an await
+        this._connectionGeneration++;
+
         // Remove the component when the element is disconnected. Skip this when the owning
         // application has already been destroyed — removing a <pc-app> disconnects it before
         // its children, taking the component systems with it.
@@ -70,6 +119,7 @@ class ComponentElement extends AsyncElement {
         }
         this._component = null;
         this._appElement = null;
+        this._resetReady();
     }
 
     /**

package/src/components/element-component.ts

@@ -1,9 +1,11 @@
-import { Color, ElementComponent, Vec2, Vec4 } from 'playcanvas';
+import type { ElementComponent } from 'playcanvas';
+import { Color, Vec2, Vec4 } from 'playcanvas';
 
 import { AssetElement } from '../asset';
-import { ComponentElement } from './component';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The ElementComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-element/ | `<pc-element>`} elements.
@@ -15,62 +17,62 @@ import { parseBool, parseColor, parseEnum, parseNumber, parseVec2, parseVec4 } f
 class ElementComponentElement extends ComponentElement {
     private _anchor: Vec4 = new Vec4(0.5, 0.5, 0.5, 0.5);
 
-    private _autoWidth: boolean = true;
+    private _autoWidth = true;
 
-    private _autoHeight: boolean = true;
+    private _autoHeight = true;
 
-    private _autoFitWidth: boolean = false;
+    private _autoFitWidth = false;
 
-    private _autoFitHeight: boolean = false;
+    private _autoFitHeight = false;
 
     private _color: Color = new Color(1, 1, 1, 1);
 
-    private _enableMarkup: boolean = false;
+    private _enableMarkup = false;
 
-    private _fontAsset: string = '';
+    private _fontAsset = '';
 
-    private _fontSize: number = 32;
+    private _fontSize = 32;
 
-    private _maxFontSize: number = 32;
+    private _maxFontSize = 32;
 
-    private _minFontSize: number = 8;
+    private _minFontSize = 8;
 
-    private _height: number = 0;
+    private _height = 0;
 
-    private _lineHeight: number = 32;
+    private _lineHeight = 32;
 
     private _margin: Vec4 | null = null;
 
-    private _mask: boolean = false;
+    private _mask = false;
 
-    private _opacity: number = 1;
+    private _opacity = 1;
 
     private _pivot: Vec2 = new Vec2(0.5, 0.5);
 
     private _pixelsPerUnit: number | null = null;
 
-    private _spriteAsset: string = '';
+    private _spriteAsset = '';
 
-    private _spriteFrame: number = 0;
+    private _spriteFrame = 0;
 
-    private _text: string = '';
+    private _text = '';
 
-    private _textureAsset: string = '';
+    private _textureAsset = '';
 
     private _type: 'group' | 'image' | 'text' = 'group';
 
-    private _useInput: boolean = false;
+    private _useInput = false;
 
-    private _width: number = 0;
+    private _width = 0;
 
-    private _wrapLines: boolean = false;
+    private _wrapLines = false;
 
     /** @ignore */
     constructor() {
         super('element');
     }
 
-    initComponent() {
+    protected initComponent() {
         const component = this.component as any;
         if (!component) {
             return;
@@ -89,7 +91,7 @@ class ElementComponentElement extends ComponentElement {
         component._dirtifyMask?.();
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             anchor: this._anchor,
             autoWidth: this._autoWidth,
@@ -774,10 +776,4 @@ class ElementComponentElement extends ComponentElement {
 
 customElements.define('pc-element', ElementComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-element': ElementComponentElement;
-    }
-}
-
 export { ElementComponentElement };

package/src/components/gsplat-component.ts

@@ -1,9 +1,10 @@
-import { GSplatComponent } from 'playcanvas';
+import type { GSplatComponent } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { AssetElement } from '../asset';
 import { parseBool, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The GSplatComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-gsplat/ | `<pc-gsplat>`} elements.
@@ -30,7 +31,7 @@ class GSplatComponentElement extends ComponentElement {
         super('gsplat');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             asset: AssetElement.get(this._asset),
             castShadows: this._castShadows,
@@ -216,10 +217,4 @@ class GSplatComponentElement extends ComponentElement {
 
 customElements.define('pc-gsplat', GSplatComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-gsplat': GSplatComponentElement;
-    }
-}
-
 export { GSplatComponentElement };

package/src/components/layoutchild-component.ts

@@ -1,8 +1,9 @@
-import { LayoutChildComponent } from 'playcanvas';
+import type { LayoutChildComponent } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
@@ -31,7 +32,7 @@ class LayoutChildComponentElement extends ComponentElement {
         super('layoutchild');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             minWidth: this._minWidth,
             minHeight: this._minHeight,
@@ -230,10 +231,4 @@ class LayoutChildComponentElement extends ComponentElement {
 
 customElements.define('pc-layoutchild', LayoutChildComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-layoutchild': LayoutChildComponentElement;
-    }
-}
-
 export { LayoutChildComponentElement };

package/src/components/layoutgroup-component.ts

@@ -1,8 +1,19 @@
-import { FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, LayoutGroupComponent, ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL, Vec2, Vec4 } from 'playcanvas';
+import type { LayoutGroupComponent } from 'playcanvas';
+import {
+    FITTING_NONE,
+    FITTING_STRETCH,
+    FITTING_SHRINK,
+    FITTING_BOTH,
+    ORIENTATION_HORIZONTAL,
+    ORIENTATION_VERTICAL,
+    Vec2,
+    Vec4
+} from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseEnum, parseVec2, parseVec4 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const orientations = new Map<'horizontal' | 'vertical', number>([
     ['horizontal', ORIENTATION_HORIZONTAL],
     ['vertical', ORIENTATION_VERTICAL]
@@ -47,7 +58,7 @@ class LayoutGroupComponentElement extends ComponentElement {
         super('layoutgroup');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             orientation: orientations.get(this._orientation),
             reverseX: this._reverseX,
@@ -295,10 +306,4 @@ class LayoutGroupComponentElement extends ComponentElement {
 
 customElements.define('pc-layoutgroup', LayoutGroupComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-layoutgroup': LayoutGroupComponentElement;
-    }
-}
-
 export { LayoutGroupComponentElement };