@playcanvas/web-components 0.20.0 → 0.21.0

package/src/components/anim-clip.ts

@@ -1,7 +1,8 @@
-import type { Asset, EventHandle } from 'playcanvas';
+import type { Asset } from 'playcanvas';
 import { AnimTrack } from 'playcanvas';
 
-import { AssetElement, useAsset } from '../asset';
+import { AssetElement } from '../asset';
+import { AssetBinding } from '../asset-binding';
 import { AsyncElement } from '../async-element';
 import { ModelElement } from '../model';
 import { parseBool, parseNumber } from '../parse';
@@ -39,6 +40,12 @@ class AnimClipElement extends AsyncElement {
 
     private _asset = '';
 
+    /**
+     * Watches the current source asset while it loads. Starting a new resolution or
+     * disconnecting cancels it, so a superseded source can never hand its track to the parent.
+     */
+    private _binding = new AssetBinding();
+
     /**
      * 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
@@ -47,22 +54,14 @@ class AnimClipElement extends AsyncElement {
      */
     private _connectionGeneration = 0;
 
-    private _errorHandle: EventHandle | null = null;
-
     /**
      * Incremented on every track resolution and on disconnect, and captured by a resolution when
-     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
-     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     * it starts. A resolution that resumes from an await abandons itself if the value has moved
+     * on, so a superseded resolution cannot hand a stale track to the parent. The asset
+     * subscription itself is guarded by the binding above.
      */
     private _loadGeneration = 0;
 
-    /**
-     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
-     * Held so that whatever supersedes the resolution can detach the handlers from the asset,
-     * rather than leave them registered until the asset settles (or forever, if it never does).
-     */
-    private _loadHandle: EventHandle | null = null;
-
     private _loop = true;
 
     private _name = '';
@@ -112,7 +111,7 @@ class AnimClipElement extends AsyncElement {
         // Invalidate any connectedCallback or track resolution still suspended on an await
         this._connectionGeneration++;
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
 
         // Uses the cached parent rather than a fresh lookup, since parentElement is already null
         // by now. The component itself is null if the whole <pc-app> is being torn down —
@@ -135,13 +134,6 @@ class AnimClipElement extends AsyncElement {
         return animElement;
     }
 
-    private _detachLoadHandlers() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-        this._errorHandle?.off();
-        this._errorHandle = null;
-    }
-
     /**
      * Reports a name-validation failure from the owning `<pc-anim>`, once per name value.
      *
@@ -169,35 +161,20 @@ class AnimClipElement extends AsyncElement {
         this._animElement = animElement;
 
         const generation = ++this._loadGeneration;
-        this._detachLoadHandlers();
+        this._binding.cancel();
 
         if (this._asset) {
-            const asset = useAsset(this._asset);
+            // Every path that moves _loadGeneration also rebinds or cancels the binding, so a
+            // delivery below is always current.
+            const asset = this._binding.bind(this._asset, {
+                load: (loaded) => this._extractTrack(loaded, `asset '${this._asset}'`),
+                error: () => {
+                    this._warnSource(`pc-anim-clip '${this._name}' - asset '${this._asset}' failed to load - clip not assigned`);
+                }
+            });
             if (!asset) {
                 this._warnSource(`pc-anim-clip '${this._name}' could not find asset '${this._asset}' - clip not assigned`);
-                return;
-            }
-            if (asset.loaded) {
-                this._extractTrack(asset, `asset '${this._asset}'`);
-                return;
             }
-            // Whichever of load/error fires first detaches the other. The generation is
-            // re-checked even though a superseded handler is detached: the detach relies on how
-            // the engine's event emitter treats removal, while the check holds on its own.
-            this._loadHandle = asset.once('load', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._extractTrack(asset, `asset '${this._asset}'`);
-            });
-            this._errorHandle = asset.once('error', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._warnSource(`pc-anim-clip '${this._name}' - asset '${this._asset}' failed to load - clip not assigned`);
-            });
             return;
         }
 

package/src/components/anim-component.ts

@@ -55,7 +55,7 @@ type PlaybackState = {
  *
  * @category Components
  */
-class AnimComponentElement extends ComponentElement {
+class AnimComponentElement extends ComponentElement<AnimComponent> {
     /**
      * Whether playback starts automatically once a clip is assigned.
      */
@@ -168,6 +168,9 @@ class AnimComponentElement extends ComponentElement {
      */
     private _applyRootBone() {
         const component = this.component;
+        if (!component) {
+            return;
+        }
 
         // A non-null root this element did not assign came through the engine API. A fresh
         // component starts at null, which is always reclaimable.
@@ -252,7 +255,7 @@ class AnimComponentElement extends ComponentElement {
      * declared `clip` selection can apply before any asset has loaded.
      */
     private _assignClip(clip: AnimClipElement) {
-        this.component.assignAnimation(clip.name, clip._track ?? AnimTrack.EMPTY, undefined, clip.speed, clip.loop);
+        this.component?.assignAnimation(clip.name, clip._track ?? AnimTrack.EMPTY, undefined, clip.speed, clip.loop);
     }
 
     /**
@@ -586,11 +589,12 @@ class AnimComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas anim component.
-     * @returns The anim component.
+     * Gets the underlying PlayCanvas anim component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The anim component, or `null`.
      */
-    get component(): AnimComponent {
-        return super.component as AnimComponent;
+    get component(): AnimComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/audio-listener-component.ts

@@ -16,18 +16,19 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class AudioListenerComponentElement extends ComponentElement {
+class AudioListenerComponentElement extends ComponentElement<AudioListenerComponent> {
     /** @ignore */
     constructor() {
         super('audiolistener');
     }
 
     /**
-     * Gets the underlying PlayCanvas audio listener component.
-     * @returns The audio listener component.
+     * Gets the underlying PlayCanvas audio listener component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The audio listener component, or `null`.
      */
-    get component(): AudioListenerComponent {
-        return super.component as AudioListenerComponent;
+    get component(): AudioListenerComponent | null {
+        return super.component;
     }
 }
 

package/src/components/button-component.ts

@@ -2,7 +2,8 @@ import type { ButtonComponent } from 'playcanvas';
 import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Color, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
-import { parseBool, parseColor, parseEnum, parseNumber, parseVec4, resolveEntity } from '../parse';
+import { resolveEntity } from '../entity-reference';
+import { parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -26,7 +27,7 @@ const transitionModes = new Map<'tint' | 'sprite', number>([
  *
  * @category Components
  */
-class ButtonComponentElement extends ComponentElement {
+class ButtonComponentElement extends ComponentElement<ButtonComponent> {
     private _active = true;
 
     private _image = '';
@@ -102,11 +103,12 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas button component.
-     * @returns The button component.
+     * Gets the underlying PlayCanvas button component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The button component, or `null`.
      */
-    get component(): ButtonComponent {
-        return super.component as ButtonComponent;
+    get component(): ButtonComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/camera-component.ts

@@ -50,7 +50,7 @@ const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2
  *
  * @category Components
  */
-class CameraComponentElement extends ComponentElement {
+class CameraComponentElement extends ComponentElement<CameraComponent> {
     private _clearColor = new Color(0.75, 0.75, 0.75, 1);
 
     private _clearColorBuffer = true;
@@ -177,11 +177,12 @@ class CameraComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas camera component.
-     * @returns The camera component.
+     * Gets the underlying PlayCanvas camera component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The camera component, or `null`.
      */
-    get component(): CameraComponent {
-        return super.component as CameraComponent;
+    get component(): CameraComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/collision-component.ts

@@ -25,7 +25,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class CollisionComponentElement extends ComponentElement {
+class CollisionComponentElement extends ComponentElement<CollisionComponent> {
     private _angularOffset: Quat = new Quat();
 
     private _axis = 1;
@@ -91,11 +91,12 @@ class CollisionComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas collision component.
-     * @returns The collision component.
+     * Gets the underlying PlayCanvas collision component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The collision component, or `null`.
      */
-    get component(): CollisionComponent {
-        return super.component as CollisionComponent;
+    get component(): CollisionComponent | null {
+        return super.component;
     }
 
     set angularOffset(value: Quat) {

package/src/components/component.ts

@@ -10,12 +10,12 @@ import { parseBool } from '../parse';
  *
  * @category Components
  */
-class ComponentElement extends AsyncElement {
+class ComponentElement<T extends Component = Component> extends AsyncElement {
     private _componentName: string;
 
     private _enabled = true;
 
-    private _component: Component | null = null;
+    private _component: T | null = null;
 
     private _appElement: AppElement | null = null;
 
@@ -97,7 +97,9 @@ class ComponentElement extends AsyncElement {
             return;
         }
 
-        this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+        // The name passed by the subclass selects the engine system that creates its T - a
+        // pairing the type system cannot express, so it is asserted this once
+        this._component = entity.addComponent(this._componentName, this.getInitialComponentData()) as T | null;
     }
 
     private async _addComponent() {
@@ -219,7 +221,7 @@ class ComponentElement extends AsyncElement {
      * before accessing it.
      * @returns The component instance, or `null`.
      */
-    get component(): Component | null {
+    get component(): T | null {
         return this._component;
     }
 

package/src/components/element-component.ts

@@ -25,7 +25,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class ElementComponentElement extends ComponentElement {
+class ElementComponentElement extends ComponentElement<ElementComponent> {
     private _anchor: Vec4 = new Vec4(0.5, 0.5, 0.5, 0.5);
 
     private _autoWidth = true;
@@ -158,11 +158,12 @@ class ElementComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas element component.
-     * @returns The element component.
+     * Gets the underlying PlayCanvas element component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The element component, or `null`.
      */
-    get component(): ElementComponent {
-        return super.component as ElementComponent;
+    get component(): ElementComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/gsplat-component.ts

@@ -19,7 +19,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class GSplatComponentElement extends ComponentElement {
+class GSplatComponentElement extends ComponentElement<GSplatComponent> {
     private _asset = '';
 
     private _castShadows = false;
@@ -49,11 +49,12 @@ class GSplatComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas gsplat component.
-     * @returns The gsplat component.
+     * Gets the underlying PlayCanvas gsplat component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The gsplat component, or `null`.
      */
-    get component(): GSplatComponent {
-        return super.component as GSplatComponent;
+    get component(): GSplatComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/joint-component.ts

@@ -1,7 +1,8 @@
 import type { JointComponent } from 'playcanvas';
 import { Vec2, Vec3 } from 'playcanvas';
 
-import { parseBool, parseEnum, parseNumber, parseVec2, parseVec3, resolveEntity } from '../parse';
+import { resolveEntity } from '../entity-reference';
+import { parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -45,7 +46,7 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  *
  * @category Components
  */
-class JointComponentElement extends ComponentElement {
+class JointComponentElement extends ComponentElement<JointComponent> {
     /**
      * The spring damping of the joint per angular axis.
      */
@@ -254,11 +255,12 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas joint component.
-     * @returns The joint component.
+     * Gets the underlying PlayCanvas joint component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The joint component, or `null`.
      */
-    get component(): JointComponent {
-        return super.component as JointComponent;
+    get component(): JointComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/layout-child-component.ts

@@ -18,7 +18,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class LayoutChildComponentElement extends ComponentElement {
+class LayoutChildComponentElement extends ComponentElement<LayoutChildComponent> {
     private _minWidth = 0;
 
     private _minHeight = 0;
@@ -51,11 +51,12 @@ class LayoutChildComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas layout child component.
-     * @returns The layout child component.
+     * Gets the underlying PlayCanvas layout child component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The layout child component, or `null`.
      */
-    get component(): LayoutChildComponent {
-        return super.component as LayoutChildComponent;
+    get component(): LayoutChildComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/layout-group-component.ts

@@ -40,7 +40,7 @@ const fittings = new Map<'none' | 'stretch' | 'shrink' | 'both', number>([
  *
  * @category Components
  */
-class LayoutGroupComponentElement extends ComponentElement {
+class LayoutGroupComponentElement extends ComponentElement<LayoutGroupComponent> {
     private _orientation: 'horizontal' | 'vertical' = 'horizontal';
 
     private _reverseX = false;
@@ -79,11 +79,12 @@ class LayoutGroupComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas layout group component.
-     * @returns The layout group component.
+     * Gets the underlying PlayCanvas layout group component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The layout group component, or `null`.
      */
-    get component(): LayoutGroupComponent {
-        return super.component as LayoutGroupComponent;
+    get component(): LayoutGroupComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/light-component.ts

@@ -45,7 +45,7 @@ const shadowTypes = new Map<
  *
  * @category Components
  */
-class LightComponentElement extends ComponentElement {
+class LightComponentElement extends ComponentElement<LightComponent> {
     private _cascadeBlend = 0;
 
     private _cascadeDistribution = 0.5;
@@ -132,11 +132,12 @@ class LightComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas light component.
-     * @returns The light component.
+     * Gets the underlying PlayCanvas light component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The light component, or `null`.
      */
-    get component(): LightComponent {
-        return super.component as LightComponent;
+    get component(): LightComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/particle-system-component.ts

@@ -1,6 +1,7 @@
-import type { ParticleSystemComponent } from 'playcanvas';
+import type { Asset, ParticleSystemComponent } from 'playcanvas';
 
 import { useAsset } from '../asset';
+import { AssetBinding } from '../asset-binding';
 
 import { ComponentElement } from './component';
 
@@ -18,9 +19,17 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class ParticleSystemComponentElement extends ComponentElement {
+class ParticleSystemComponentElement extends ComponentElement<ParticleSystemComponent> {
     private _asset = '';
 
+    /**
+     * The subscription to the current config asset while its load is in flight. Rebinding
+     * supersedes it and disconnect cancels it, so a superseded config — an earlier asset that
+     * finishes loading after its replacement, or a callback left behind by a previous
+     * connection — can never configure the component.
+     */
+    private _binding = new AssetBinding();
+
     /** @ignore */
     constructor() {
         super('particlesystem');
@@ -28,28 +37,54 @@ class ParticleSystemComponentElement extends ComponentElement {
 
     protected getInitialComponentData() {
         const asset = useAsset(this._asset);
-        // A lazy config has no resource yet - _loadAsset applies it once the load completes
+        // A lazy config has no resource yet - the config binding applies it once the load
+        // completes
         if (!asset || !asset.resource) {
             return {};
         }
 
-        if ((asset.resource as any).colorMapAsset) {
-            const id = (asset.resource as any).colorMapAsset;
-            const colorMapAsset = useAsset(id)?.id;
-            if (colorMapAsset) {
-                (asset.resource as any).colorMapAsset = colorMapAsset;
-            }
+        this._resolveColorMap(asset.resource);
+        return asset.resource;
+    }
+
+    protected initComponent() {
+        // A loaded config already arrived through getInitialComponentData - the binding is only
+        // needed for a load still in flight. Resolution here also starts a lazy config's load.
+        const asset = useAsset(this._asset);
+        if (asset && !asset.loaded) {
+            this._bindConfig();
         }
+    }
 
-        return asset.resource;
+    disconnectedCallback() {
+        // The binding dies with the connection, so a config that finishes loading later cannot
+        // configure the component a reconnection creates - that connection binds afresh.
+        this._binding.cancel();
+        super.disconnectedCallback();
     }
 
     /**
-     * Gets the underlying PlayCanvas particle system component.
-     * @returns The particle system component.
+     * Gets the underlying PlayCanvas particle system component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The particle system component, or `null`.
      */
-    get component(): ParticleSystemComponent {
-        return super.component as ParticleSystemComponent;
+    get component(): ParticleSystemComponent | null {
+        return super.component;
+    }
+
+    /**
+     * Rewrites the config's `colorMapAsset` from the `pc-asset` id it is authored with to the
+     * engine asset id the component resolves, starting the texture's load if it is lazy. The
+     * rewrite is in place, so a config applied again — a host cycle, a reconnection — is already
+     * resolved and passes through unchanged.
+     */
+    private _resolveColorMap(resource: any) {
+        if (resource.colorMapAsset) {
+            const colorMapAsset = useAsset(resource.colorMapAsset)?.id;
+            if (colorMapAsset) {
+                resource.colorMapAsset = colorMapAsset;
+            }
+        }
     }
 
     private applyConfig(resource: any) {
@@ -57,6 +92,8 @@ class ParticleSystemComponentElement extends ComponentElement {
             return;
         }
 
+        this._resolveColorMap(resource);
+
         // Set all the config properties on the component
         for (const key in resource) {
             if (Object.hasOwn(resource, key)) {
@@ -65,21 +102,10 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
     }
 
-    private async _loadAsset() {
-        await this.closestApp?.ready();
-
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            return;
-        }
-
-        if (asset.loaded) {
-            this.applyConfig(asset.resource);
-        } else {
-            asset.once('load', () => {
-                this.applyConfig(asset.resource);
-            });
-        }
+    private _bindConfig() {
+        this._binding.bind(this._asset, {
+            load: (asset: Asset) => this.applyConfig(asset.resource)
+        });
     }
 
     /**
@@ -89,7 +115,7 @@ class ParticleSystemComponentElement extends ComponentElement {
     set asset(value: string) {
         this._asset = value;
         if (this.isConnected) {
-            this._loadAsset();
+            this._bindConfig();
         }
     }
 

package/src/components/render-component.ts

@@ -24,7 +24,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class RenderComponentElement extends ComponentElement {
+class RenderComponentElement extends ComponentElement<RenderComponent> {
     private _castShadows = true;
 
     private _material = '';
@@ -48,11 +48,12 @@ class RenderComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas render component.
-     * @returns The render component.
+     * Gets the underlying PlayCanvas render component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The render component, or `null`.
      */
-    get component(): RenderComponent {
-        return super.component as RenderComponent;
+    get component(): RenderComponent | null {
+        return super.component;
     }
 
     /**