@playcanvas/web-components 0.19.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 { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } 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 = '';
@@ -76,7 +77,9 @@ class ButtonComponentElement extends ComponentElement {
 
         // The image entity defaults to the button's own entity (which carries the image element)
         // when no explicit reference is provided.
-        const imageEntity = this._image ? getEntity(this._image) : this.closestEntity?.entity;
+        const imageEntity = this._image
+            ? resolveEntity(this._image, this, 'image', 'reference ignored')
+            : this.closestEntity?.entity;
         if (imageEntity) {
             data.imageEntity = imageEntity;
         }
@@ -100,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;
     }
 
     /**
@@ -127,22 +131,28 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
-     * element is used for visual transitions. Defaults to the button's own entity — inside a
-     * `<pc-model>`, that is the model's host entity, so supply an explicit reference to target a
-     * UI entity instead.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions. An exact name
+     * resolves against the nearest enclosing entity first, then outward, then the document.
+     * Defaults to the button's own entity — inside a `<pc-model>`, that is the model's host
+     * entity, so supply an explicit reference to target a UI entity instead. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The image entity reference.
      */
     set image(value: string) {
         this._image = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.imageEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'image', 'reference ignored');
+            if (entity) {
+                this.component.imageEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity whose image element is used for visual transitions, or empty for
+     * the button's own entity.
      * @returns The image entity reference.
      */
     get image() {

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 { getEntity, parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } from '../parse';
+import { resolveEntity } from '../entity-reference';
+import { parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -25,7 +26,12 @@ export type MotionMode = 'locked' | 'limited' | 'free';
  * primary axis: a hinge rotates about it, a slider translates along it and a ball joint twists
  * about it. The constrained bodies are referenced by `entity-a` and `entity-b`, both of which need
  * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
- * space. The underlying engine component is in alpha, so its API may change.
+ * space. A reference can name any entity-fronting element — `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`, so a ragdoll can join a model's own skeleton nodes by name — and a name resolves
+ * against the nearest enclosing entity first, then outward through the entity hierarchy, then the
+ * document, while a `#` selector resolves document-wide. A `<template>` prefab with one
+ * entity-fronting root can therefore wire its joints by name and stay self-contained when cloned.
+ * The underlying engine component is in alpha, so its API may change.
  *
  * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
  * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
@@ -40,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.
      */
@@ -210,8 +216,8 @@ class JointComponentElement extends ComponentElement {
             breakImpulse: this._breakImpulse,
             enableCollision: this._enableCollision,
             enableLimits: this._enableLimits,
-            entityA: getEntity(this._entityA),
-            entityB: getEntity(this._entityB),
+            entityA: resolveEntity(this._entityA, this, 'entity-a', 'constraint not created'),
+            entityB: resolveEntity(this._entityB, this, 'entity-b', 'constraint not created'),
             limits: this._limits,
             linearDamping: this._linearDamping,
             linearEquilibrium: this._linearEquilibrium,
@@ -249,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;
     }
 
     /**
@@ -495,20 +502,24 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the first constrained body. The reference resolves when it is set, so an entity created
-     * later is picked up by setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. The reference
+     * resolves when it is set, so an entity created later is picked up by setting the attribute
+     * again. A non-empty reference that does not resolve warns, naming which of the two causes it
+     * hit.
      * @param value - The first body's entity reference.
      */
     set entityA(value: string) {
         this._entityA = value;
         if (this.component) {
-            this.component.entityA = getEntity(value);
+            this.component.entityA = resolveEntity(value, this, 'entity-a', 'constraint not created');
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` providing the first constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the first constrained body.
      * @returns The first body's entity reference.
      */
     get entityA() {
@@ -516,21 +527,26 @@ class JointComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` providing
-     * the second constrained body, or empty to constrain the first body to a fixed point in world
-     * space. The reference resolves when it is set, so an entity created later is picked up by
-     * setting the attribute again.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty to constrain the
+     * first body to a fixed point in world space. An exact name resolves against the nearest
+     * enclosing entity first, then outward, then the document. The reference resolves when it is
+     * set, so an entity created later is picked up by setting the attribute again. A non-empty
+     * reference that does not resolve warns; an empty one is the documented world-space case and
+     * stays silent.
      * @param value - The second body's entity reference.
      */
     set entityB(value: string) {
         this._entityB = value;
         if (this.component) {
-            this.component.entityB = getEntity(value);
+            this.component.entityB = resolveEntity(value, this, 'entity-b', 'constraint not created');
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` providing the second constrained body.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the element providing the second constrained body, or empty for the
+     * world-space case.
      * @returns The second body's entity reference.
      */
     get entityB() {

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