@playcanvas/web-components 0.19.0 → 0.21.0

package/src/components/sound-component.ts

@@ -18,7 +18,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class SoundComponentElement extends ComponentElement {
+class SoundComponentElement extends ComponentElement<SoundComponent> {
     private _distanceModel: 'exponential' | 'inverse' | 'linear' = 'linear';
 
     private _maxDistance = 10000;
@@ -51,11 +51,12 @@ class SoundComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
-    get component(): SoundComponent {
-        return super.component as SoundComponent;
+    get component(): SoundComponent | null {
+        return super.component;
     }
 
     /**

package/src/entity-reference.ts

@@ -0,0 +1,237 @@
+/**
+ * Resolves entity reference strings against the document. A reference beginning with `#` is a
+ * document-wide selector (an element id, or any selector rooted in one); anything else is an
+ * entity name, resolved lexically through the entity hierarchy first and against the document
+ * after — never as a selector or an id.
+ *
+ * Unlike the attribute parsers in `parse.ts`, these helpers touch the DOM, and `findEntityElement`
+ * and `getEntity` return `null` instead of falling back to a default. They also do not warn -
+ * what an unresolved reference means depends on the element holding it - so elements report
+ * through `resolveEntity`, which takes that meaning as parameters, and `pc-script` builds its own
+ * message from the lower-level pieces.
+ */
+
+import type { Entity } from 'playcanvas';
+
+/**
+ * Runs querySelector, absorbing the SyntaxError an unparseable selector throws - references are
+ * arbitrary author text, so a lookup must fail to `null`, never throw.
+ *
+ * @param selector - The selector to query.
+ * @returns The matched element, or `null`.
+ */
+const query = (selector: string): Element | null => {
+    try {
+        return document.querySelector(selector);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Runs a lookup against one scope, checking the scope element itself before its subtree — a
+ * reference deep in a cloned prefab must be able to name the prefab's root. Absorbs the
+ * SyntaxError of an invalid selector like {@link query}: escaping quotes and backslashes does not
+ * make arbitrary text a valid CSS string (a reference containing a newline still throws), so a
+ * lookup must fail to `null`, never throw.
+ *
+ * @param scope - The element whose inclusive subtree to search.
+ * @param selector - The selector to query.
+ * @returns The matched element, or `null`.
+ */
+const queryScope = (scope: Element, selector: string): Element | null => {
+    try {
+        return scope.matches(selector) ? scope : scope.querySelector(selector);
+    } catch {
+        return null;
+    }
+};
+
+/**
+ * Reads the entity a resolved element is backing, through the `entity` accessor every
+ * entity-fronting element exposes. `null` for no element, and for an element backing nothing.
+ *
+ * @param element - The element to read, or `null`.
+ * @returns The backing entity, or `null`.
+ */
+const entityOf = (element: Element | null): Entity | null => {
+    return (element as { entity?: Entity } | null)?.entity ?? null;
+};
+
+/**
+ * The elements that front an entity: what a bare name can resolve to, and the scopes of the
+ * lexical name lookup.
+ */
+const ENTITY_KINDS = ['pc-entity', 'pc-model', 'pc-node'] as const;
+
+/**
+ * The entity-fronting elements as one selector, for the scope walk.
+ */
+const ENTITY_SCOPES = ENTITY_KINDS.join(', ');
+
+/**
+ * Resolves a reference string to the element it names. The grammar is closed — every reference
+ * has exactly one interpretation:
+ *
+ * - A reference beginning with `#` is a document-wide CSS selector — an element id (`#body`), or
+ *   any selector rooted in one (`#hud pc-entity`). It is authoritative: the name lookup never
+ *   runs for it, so an unusually named entity cannot shadow it.
+ * - Any other reference is the name of an entity-fronting element (`<pc-entity>`, `<pc-model>` or
+ *   `<pc-node>` — for a node, the glTF node name it binds), and nothing else. A bare reference is
+ *   never interpreted as a selector or an element id, so adding or renaming elements can never
+ *   change which form it takes.
+ *
+ * When `from` is supplied, a name resolves lexically first: the closest entity-fronting
+ * ancestor's inclusive subtree, then each outer entity-fronting ancestor, then the containing
+ * `<pc-app>`, then the document. This is what lets a `<template>` prefab reference its own
+ * entities by name — every clone resolves within itself before a document-wide lookup could reach
+ * an earlier clone — provided the prefab has a single entity-fronting root to be the enclosing
+ * scope.
+ *
+ * Separate from {@link getEntity} so a caller reporting a failure can tell the causes apart
+ * ({@link unresolvedCause} words them): nothing in the document matches the reference, or
+ * something matches but is not backing an entity (yet, or ever).
+ *
+ * @param ref - The reference string to resolve.
+ * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+ * name lookup. Omitted, the name lookup is document-wide only.
+ * @returns The matched element, or `null`.
+ * @internal
+ */
+export const findEntityElement = (ref: string, from?: Element): Element | null => {
+    if (!ref) {
+        return null;
+    }
+
+    // A '#' reference is document-wide and bypasses the name lookup entirely - an entity named
+    // '#body' must never shadow the element whose id is 'body'.
+    if (ref.startsWith('#')) {
+        return query(ref);
+    }
+
+    // The name lands inside a quoted CSS string, so its quotes and backslashes are escaped -
+    // a name like `say "hi"` must resolve, not turn the lookup into a SyntaxError.
+    const escaped = ref.replace(/["\\]/g, '\\$&');
+    const nameSelector = ENTITY_KINDS.map(kind => `${kind}[name="${escaped}"]`).join(', ');
+
+    if (from) {
+        let scope = from.parentElement?.closest(ENTITY_SCOPES);
+        while (scope) {
+            const element = queryScope(scope, nameSelector);
+            if (element) {
+                return element;
+            }
+            scope = scope.parentElement?.closest(ENTITY_SCOPES);
+        }
+
+        const app = from.parentElement?.closest('pc-app');
+        if (app) {
+            const element = queryScope(app, nameSelector);
+            if (element) {
+                return element;
+            }
+        }
+    }
+
+    return query(nameSelector);
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing an entity-fronting element
+ * (`<pc-entity>`, `<pc-model>` or `<pc-node>`). The reference is a name — resolved lexically
+ * through the entity hierarchy first when `from` is supplied — or a document-wide `#` selector
+ * ({@link findEntityElement} details the grammar and order). Returns `null` if no matching
+ * element (or backing entity) is found.
+ *
+ * @param ref - The reference string to resolve.
+ * @param from - The element resolving the reference, whose entity-fronting ancestors scope the
+ * name lookup. Omitted, the name lookup is document-wide only.
+ * @returns The resolved entity, or `null`.
+ * @internal
+ */
+export const getEntity = (ref: string, from?: Element): Entity | null => {
+    return entityOf(findEntityElement(ref, from));
+};
+
+/**
+ * Describes why a non-empty reference did not resolve, for a warning. Three causes, because they
+ * have three different fixes: nothing matches (usually a typo), the matched element is not backing
+ * an entity yet (usually timing - a `pc-node` whose asset has not loaded - so resolving again
+ * later can work), or the matched element can never back one (the reference points at the wrong
+ * element, so only correcting it can). Capability is the `entity` accessor every entity-backing
+ * element inherits from EntityBaseElement.
+ *
+ * @param element - The element the reference matched, or `null` when nothing did.
+ * @returns The cause, phrased to follow `could not resolve ... -`.
+ * @internal
+ */
+export const unresolvedCause = (element: Element | null): string => {
+    if (!element) {
+        return 'nothing in the document matches it';
+    }
+    const tag = `<${element.tagName.toLowerCase()}>`;
+    return 'entity' in element
+        ? `${tag} matches it but is not backing an entity yet`
+        : `${tag} matches it but cannot back an entity`;
+};
+
+/**
+ * Builds the migration pointer for a bare reference that names nothing but matches the id of an
+ * entity-fronting element - it was almost certainly meant as an id, so point at the form that
+ * expresses it, escaped so the suggestion actually parses as a selector (an id like `a:b` must
+ * be written `#a\:b`). Empty when the reference is already a `#` form, matches no id, or the id
+ * belongs to an element that could never back an entity - suggesting it would only trade this
+ * warning for the wrong-target one.
+ *
+ * @param ref - The unresolved reference.
+ * @param prefix - Text the suggested form must carry in the caller's syntax (e.g. `entity:`).
+ * @returns The advice sentence, or an empty string.
+ * @internal
+ */
+export const idHint = (ref: string, prefix = ''): string => {
+    const match = !ref.startsWith('#') && document.getElementById(ref);
+    return match && 'entity' in match
+        ? `A bare reference is a name - write '${prefix}#${CSS.escape(ref)}' to reference the element with that id.`
+        : '';
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing an entity-fronting element, scoped to
+ * the resolving element ({@link findEntityElement} details the order) and warning when a
+ * non-empty reference does not resolve - otherwise the reference fails silently, invisible
+ * except through the behavior it should have driven. The message names which of the three causes
+ * ({@link unresolvedCause}) it hit, and advises reassigning later only when that can work.
+ *
+ * An empty reference stays silent: it is the unset state of an optional attribute, and on some
+ * elements (`pc-joint` `entity-b`, `pc-button` `image`) a documented value of its own.
+ *
+ * @param ref - The reference string to resolve.
+ * @param from - The element resolving the reference; scopes the lookup and names the message.
+ * @param attribute - The attribute being resolved, for the message.
+ * @param consequence - What the unresolved reference means for the element, for the message.
+ * @returns The resolved entity, or `null`.
+ * @internal
+ */
+export const resolveEntity = (ref: string, from: Element, attribute: string, consequence: string): Entity | null => {
+    if (!ref) {
+        return null;
+    }
+
+    const element = findEntityElement(ref, from);
+    const entity = entityOf(element);
+    if (!entity) {
+        let advice = `Assign ${attribute} again once the entity exists.`;
+        if (element && !('entity' in element)) {
+            advice = `Point ${attribute} at a pc-entity, pc-model or pc-node instead.`;
+        } else if (!element) {
+            const hint = idHint(ref);
+            if (hint) {
+                advice = hint;
+            }
+        }
+        console.warn(
+            `${from.tagName.toLowerCase()} could not resolve ${attribute} '${ref}' - ${unresolvedCause(element)} - ${consequence}. ${advice}`
+        );
+    }
+    return entity;
+};

package/src/material.ts

@@ -23,10 +23,10 @@ import {
     StandardMaterial,
     Vec2
 } from 'playcanvas';
-import type { EventHandle, Texture } from 'playcanvas';
+import type { Texture } from 'playcanvas';
 
 import type { AppElement } from './app';
-import { useAsset } from './asset';
+import { AssetBinding } from './asset-binding';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2 } from './parse';
 
 /** The blend modes for a material. */
@@ -318,11 +318,12 @@ class MaterialElement extends HTMLElement {
     private _useTonemap = true;
 
     /**
-     * Pending `load` handlers, one per texture slot. A slot's handler is torn down when the slot is
-     * reassigned or the element disconnects, so a late-arriving asset can never write a texture the
-     * element no longer wants.
+     * One asset binding per texture slot, created on first use and kept for the element's
+     * lifetime. A slot's binding is superseded when the slot is reassigned and cancelled when the
+     * element disconnects, so a late-arriving asset can never write a texture the element no
+     * longer wants.
      */
-    private _mapHandles = new Map<TextureSlot, EventHandle>();
+    private _mapBindings = new Map<TextureSlot, AssetBinding>();
 
     private _updateScheduled = false;
 
@@ -461,10 +462,9 @@ class MaterialElement extends HTMLElement {
     }
 
     disconnectedCallback() {
-        for (const handle of this._mapHandles.values()) {
-            handle.off();
+        for (const binding of this._mapBindings.values()) {
+            binding.cancel();
         }
-        this._mapHandles.clear();
 
         if (this.material) {
             this.material.destroy();
@@ -518,16 +518,24 @@ class MaterialElement extends HTMLElement {
     }
 
     /**
-     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when it
-     * has not already. An empty id clears the slot.
+     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when
+     * it has not already. An empty id clears the slot; a slot keeps its current texture while
+     * the new asset loads, and also across a failed load - a later reload can still deliver.
      *
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.
      */
     private _setMap(id: string, slot: TextureSlot) {
-        // Drop any load still pending for this slot - its texture is no longer the one we want
-        this._mapHandles.get(slot)?.off();
-        this._mapHandles.delete(slot);
+        let binding = this._mapBindings.get(slot);
+        if (!binding) {
+            binding = new AssetBinding();
+            this._mapBindings.set(slot, binding);
+        }
+
+        // Drop any load still pending for this slot - its texture is no longer the one we want.
+        // Cancelled here rather than left to the bind below, which the material-less and
+        // clear-slot returns never reach.
+        binding.cancel();
 
         if (!this.material) return;
 
@@ -537,21 +545,9 @@ class MaterialElement extends HTMLElement {
             return;
         }
 
-        const asset = useAsset(id);
-        if (!asset) return;
-
-        if (asset.loaded) {
-            this._applyMap(slot, asset.resource as Texture);
-            return;
-        }
-
-        this._mapHandles.set(
-            slot,
-            asset.once('load', () => {
-                this._mapHandles.delete(slot);
-                this._applyMap(slot, asset.resource as Texture);
-            })
-        );
+        binding.bind(id, {
+            load: (asset) => this._applyMap(slot, asset.resource as Texture)
+        });
     }
 
     /**

package/src/model.ts

@@ -1,7 +1,7 @@
-import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
+import type { ContainerResource, Entity } from 'playcanvas';
 import { Vec3 } from 'playcanvas';
 
-import { useAsset } from './asset';
+import { AssetBinding } from './asset-binding';
 import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
@@ -168,20 +168,19 @@ class ModelElement extends EntityOwnerElement {
 
     /**
      * Incremented on every new load, on disconnect, and when the host entity dies, and captured
-     * by a load when it starts. A load that resumes from an await or a load callback abandons
-     * itself if the value has moved on, so a superseded load can neither instantiate a second
-     * content root nor parent one under a host a newer cycle has already replaced.
+     * by a load when it starts. A load that resumes from an await abandons itself if the value
+     * has moved on, so a superseded load can neither instantiate a second content root nor
+     * parent one under a host a newer cycle has already replaced. The asset subscription itself
+     * is guarded by the binding below.
      */
     private _loadGeneration = 0;
 
     /**
-     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
-     * so that whatever supersedes the load can detach the handlers from the asset, rather than
-     * leave them registered until the asset settles (or forever, if it never does).
+     * The subscription to the current container asset while it is loading. Whatever supersedes
+     * the load — a newer load, a disconnect, the host dying — cancels it, so the asset settling
+     * later cannot deliver to a load that no longer owns the element.
      */
-    private _loadHandle: EventHandle | null = null;
-
-    private _errorHandle: EventHandle | null = null;
+    private _binding = new AssetBinding();
 
     /**
      * The root entity of the instantiated model content, parented beneath the host entity.
@@ -287,7 +286,7 @@ class ModelElement extends EntityOwnerElement {
         // resets the element. The generation guard comes first so a load suspended on an await
         // cannot resume against the torn-down element.
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         this._entity?.destroy();
     }
 
@@ -308,18 +307,11 @@ class ModelElement extends EntityOwnerElement {
      */
     protected override _onEntityDestroy(entity: Entity) {
         this._loadGeneration++;
-        this._detachLoadHandlers();
+        this._binding.cancel();
         this._contentEntity = null;
         super._onEntityDestroy(entity);
     }
 
-    private _detachLoadHandlers() {
-        this._loadHandle?.off();
-        this._loadHandle = null;
-        this._errorHandle?.off();
-        this._errorHandle = null;
-    }
-
     /**
      * Resolves readiness and dispatches the `load` event. Called once the instantiated content
      * has been parented beneath the host — the host itself is already in the scene graph by
@@ -350,7 +342,7 @@ class ModelElement extends EntityOwnerElement {
 
         // Supersede any load already in flight - only the newest load may instantiate
         const generation = ++this._loadGeneration;
-        this._detachLoadHandlers();
+        this._binding.cancel();
 
         // Re-arm readiness so a waiter obtained after an asset change resolves against the new
         // content. A no-op on first connection, where readiness is still pending.
@@ -383,32 +375,11 @@ class ModelElement extends EntityOwnerElement {
             return;
         }
 
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            // A non-empty id that resolves to nothing is a dead end - say so rather than staying
-            // silently pending.
-            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
-            return;
-        }
-
-        if (asset.loaded) {
-            this._instantiate(asset.resource as ContainerResource);
-        } else {
-            // 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. Whichever of load/error fires first detaches the other.
-            this._loadHandle = asset.once('load', () => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
-                this._instantiate(asset.resource as ContainerResource);
-            });
-            this._errorHandle = asset.once('error', (err: string | Error) => {
-                this._detachLoadHandlers();
-                if (generation !== this._loadGeneration) {
-                    return;
-                }
+        // Every path that moves _loadGeneration also rebinds or cancels the binding, so a
+        // delivery below is always current - no generation re-check needed in the callbacks.
+        const asset = this._binding.bind(this._asset, {
+            load: ({ resource }) => this._instantiate(resource as ContainerResource),
+            error: (err) => {
                 // A failed load settles readiness with a null contentEntity, mirroring pc-asset:
                 // readiness means the load settled, not that it succeeded.
                 this.dispatchEvent(
@@ -417,7 +388,12 @@ class ModelElement extends EntityOwnerElement {
                     })
                 );
                 this._onReady();
-            });
+            }
+        });
+        if (!asset) {
+            // A non-empty id that resolves to nothing is a dead end - say so rather than staying
+            // silently pending.
+            console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
         }
     }
 

package/src/parse.ts

@@ -11,12 +11,8 @@
  *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
  * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
  *   so they never warn.
- *
- * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
- * literal, and returns `null` instead of falling back to a default.
  */
 
-import type { Entity } from 'playcanvas';
 import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { CSS_COLORS } from './colors';
@@ -322,34 +318,3 @@ export const parseVec4 = <T extends Vec4 | null>(
     }
     return new Vec4(components);
 };
-
-/**
- * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
- * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
- * entity name. Returns `null` if no matching element (or backing entity) is found.
- *
- * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
- * @internal
- */
-export const getEntity = (ref: string): Entity | null => {
-    if (!ref) {
-        return null;
-    }
-
-    let element: Element | null = null;
-
-    // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
-    // spaces) throws, in which case we fall back to id/name lookups below.
-    try {
-        element = document.querySelector(ref);
-    } catch {
-        element = null;
-    }
-
-    if (!element) {
-        element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
-    }
-
-    return (element as { entity?: Entity } | null)?.entity ?? null;
-};