@playcanvas/web-components 0.11.0 → 0.12.0

package/src/async-element.ts

@@ -1,17 +1,20 @@
-import { AppElement } from './app';
-import { EntityElement } from './entity';
+import type { AppElement } from './app';
+import type { EntityBaseElement } from './entity-base';
 
 /**
  * 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,31 +29,55 @@ 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;
     }
 
     /**
-     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
-     * ancestor. The search starts at the parent, so an element never resolves to itself.
-     * @returns The closest entity element, or `null`.
+     * The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or
+     * `null` if this element has no such ancestor. The search starts at the parent, so an element
+     * never resolves to itself.
+     * @returns The closest entity-fronting element, or `null`.
      */
-    get closestEntity(): EntityElement | null {
-        return this.parentElement?.closest('pc-entity') as EntityElement | null ?? null;
+    get closestEntity(): EntityBaseElement | null {
+        return (this.parentElement?.closest('pc-entity, pc-node') as EntityBaseElement | 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 +90,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,30 +1,38 @@
-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.
  * The CollisionComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * For `type="mesh"`, the collision geometry defaults to the host entity's own render component
+ * (its render asset) — a collider matching the visible mesh, which is what a mesh collider on a
+ * glTF node means. The default resolves each time the component applies, so a `pc-node` that
+ * retargets or rebinds picks up the new node's geometry. An entity with no asset-backed render
+ * component warns, and the collider has no shape.
+ *
  * @category Components
  */
 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 +41,7 @@ class CollisionComponentElement extends ComponentElement {
         super('collision');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             axis: this._axis,
             angularOffset: this._angularOffset,
@@ -46,6 +54,34 @@ class CollisionComponentElement extends ComponentElement {
         };
     }
 
+    protected initComponent() {
+        this._applyMeshGeometryDefault();
+    }
+
+    /**
+     * Defaults a mesh collider's geometry to the host entity's own render component. The
+     * engine's mesh collider only works with explicitly supplied geometry, and the element has
+     * no attribute to supply it - so the host's visible geometry, the meaning a mesh collider
+     * on a glTF node carries, fills the gap. Runs on every application (so a rebound `pc-node`
+     * recomputes it) and on a runtime switch to `type="mesh"`; an explicitly assigned
+     * `renderAsset` is never overwritten.
+     */
+    private _applyMeshGeometryDefault() {
+        const component = this.component;
+        if (!component || this._type !== 'mesh' || component.renderAsset !== null) {
+            return;
+        }
+
+        const asset = component.entity.render?.asset ?? null;
+        if (asset === null) {
+            console.warn(
+                `pc-collision type="mesh" on '${component.entity.name}' found no asset-backed render component to take geometry from - collider has no shape`
+            );
+            return;
+        }
+        component.renderAsset = asset;
+    }
+
     /**
      * Gets the underlying PlayCanvas collision component.
      * @returns The collision component.
@@ -135,6 +171,7 @@ class CollisionComponentElement extends ComponentElement {
         this._type = value;
         if (this.component) {
             this.component.type = value;
+            this._applyMeshGeometryDefault();
         }
     }
 
@@ -143,7 +180,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 +219,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 +232,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,7 +1,8 @@
-import { Component } from 'playcanvas';
+import type { Component } from 'playcanvas';
 
-import { AppElement } from '../app';
+import type { AppElement } from '../app';
 import { AsyncElement } from '../async-element';
+import type { EntityBaseElement } from '../entity-base';
 import { parseBool } from '../parse';
 
 /**
@@ -18,6 +19,27 @@ class ComponentElement extends AsyncElement {
 
     private _appElement: AppElement | null = null;
 
+    /**
+     * The element hosting this component, held so the host's readiness cycles can be observed
+     * even after `closestEntity` would no longer resolve (during teardown).
+     */
+    private _hostElement: EntityBaseElement | null = null;
+
+    /**
+     * The listener re-applying this component when the host's readiness cycles. Held for
+     * removal on disconnect.
+     */
+    private _hostReadyListener: EventListener | 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 +52,155 @@ 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() {
+    /**
+     * Creates the component on the host's current entity, removing it first from a previous
+     * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
+     * the entity already has a component of this type — a glTF node arriving with its authored
+     * `render` component, say — warns and leaves `component` null. The element-level warning is
+     * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
+     * production builds, which would otherwise leave a silent null.
+     */
+    private _applyComponent() {
+        const entity = this._hostElement?.entity ?? null;
+        if (this._component && this._component.entity === entity) {
+            return;
+        }
+
+        // A retarget leaves the previous component on a still-live entity - remove it so the
+        // decoration follows the element, or vanishes with a dissolved binding. A destroyed
+        // entity took its components with it.
+        const previous = this._component;
+        if (previous?.entity && previous.entity.c[this._componentName] === previous) {
+            previous.entity.removeComponent(this._componentName);
+        }
+        this._component = null;
+
+        if (!entity) {
+            return;
+        }
+
+        if (entity.c[this._componentName]) {
+            const label = this.id ? ` '${this.id}'` : '';
+            console.warn(
+                `${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`
+            );
+            return;
+        }
+
+        this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+    }
+
+    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();
-        // Add the component to the entity
-        const data = this.getInitialComponentData();
-        this._component = entityElement.entity!.addComponent(this._componentName, data);
+
+        // 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;
+        }
+
+        this._hostElement = entityElement;
+        this._applyComponent();
+
+        // Re-apply when the host's readiness cycles without this element disconnecting: a
+        // `<pc-node>` rebinding after its model reloads or retargets, or a re-created entity.
+        // The 'ready' event bubbles, so events from descendants pass through this host - only
+        // the host's own cycles count. Readiness is cycled here too, so decorations one level
+        // down re-apply the same way.
+        this._hostReadyListener = (event: Event) => {
+            if (event.target !== this._hostElement) {
+                return;
+            }
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
+            this._hostCycled();
+        };
+        entityElement.addEventListener('ready', this._hostReadyListener);
     }
 
-    initComponent() {}
+    /**
+     * Re-evaluates this component against the host's current entity: applied to a new entity,
+     * moved from a still-live old one, or removed when the host no longer fronts an entity at
+     * all. Readiness follows - it cycles with a re-application and stays unresolved while the
+     * host is unbound. Called by the host-ready listener, and directly by a `<pc-node>`
+     * dissolving its binding: the one transition that fires no ready event to ride.
+     *
+     * @internal
+     */
+    _hostCycled() {
+        this._resetReady();
+        this._applyComponent();
+        if (this._hostElement?.entity) {
+            this.initComponent();
+            this._onReady();
+        }
+    }
+
+    /**
+     * 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++;
+
+        if (this._hostElement && this._hostReadyListener) {
+            this._hostElement.removeEventListener('ready', this._hostReadyListener);
+        }
+        this._hostElement = null;
+        this._hostReadyListener = null;
+
         // 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 +209,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 };