@playcanvas/web-components 0.8.2 → 0.10.0

package/src/components/sound-slot.ts

@@ -3,6 +3,7 @@ import { SoundSlot } from 'playcanvas';
 import { AssetElement } from '../asset';
 import { AsyncElement } from '../async-element';
 import { SoundComponentElement } from './sound-component';
+import { parseBool, parseNumber } from '../parse';
 
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
@@ -28,13 +29,31 @@ class SoundSlotElement extends AsyncElement {
 
     private _volume: number = 1;
 
+    /**
+     * The `<pc-sounds>` this slot was added to, captured at connect time.
+     *
+     * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+     * `parentElement` is already `null`, so a lookup would both fail to find the component and
+     * emit a misleading "must be a direct child" warning for what is an ordinary removal.
+     */
+    private _soundElement: SoundComponentElement | null = null;
+
     /**
      * The sound slot.
      */
     soundSlot: SoundSlot | null = null;
 
     async connectedCallback() {
-        await this.soundElement?.ready();
+        const soundElement = this.soundElement;
+        await soundElement?.ready();
+
+        // The element may have been removed, or its parent torn down, while we were waiting. A
+        // <pc-app> disconnects before its children, so by the time we resume the component can
+        // already be gone - see the matching guard in disconnectedCallback below.
+        const component = soundElement?.component;
+        if (!this.isConnected || !component) {
+            return;
+        }
 
         const options = {
             autoPlay: this._autoPlay,
@@ -48,7 +67,8 @@ class SoundSlotElement extends AsyncElement {
             options.duration = this._duration;
         }
 
-        this.soundSlot = this.soundElement!.component!.addSlot(this._name, options);
+        this._soundElement = soundElement;
+        this.soundSlot = component.addSlot(this._name, options);
         this.asset = this._asset;
         if (this._autoPlay) {
             this.soundSlot!.play();
@@ -58,14 +78,19 @@ class SoundSlotElement extends AsyncElement {
     }
 
     disconnectedCallback() {
-        this.soundElement!.component!.removeSlot(this._name);
+        // Uses the cached parent rather than a fresh lookup, since parentElement is already null
+        // by now. The component itself is null if the parent <pc-sound> (or the whole <pc-app>) is
+        // being torn down — parents disconnect first and have already removed the component.
+        this._soundElement?.component?.removeSlot(this._name);
+        this._soundElement = null;
+        this.soundSlot = null;
     }
 
     protected get soundElement(): SoundComponentElement | null {
         const soundElement = this.parentElement as SoundComponentElement;
 
         if (!(soundElement instanceof SoundComponentElement)) {
-            console.warn('pc-sound-slot must be a direct child of a pc-sound element');
+            console.warn('pc-sound must be a direct child of a pc-sounds element');
             return null;
         }
 
@@ -114,12 +139,12 @@ class SoundSlotElement extends AsyncElement {
     }
 
     /**
-     * Sets the duration of the sound slot.
+     * Sets the duration of the sound slot, in seconds (or `null` to play the whole clip).
      * @param value - The duration.
      */
-    set duration(value: number) {
+    set duration(value: number | null) {
         this._duration = value;
-        if (this.soundSlot) {
+        if (this.soundSlot && value !== null) {
             this.soundSlot.duration = value;
         }
     }
@@ -128,8 +153,8 @@ class SoundSlotElement extends AsyncElement {
      * Gets the duration of the sound slot.
      * @returns The duration.
      */
-    get duration() {
-        return this._duration as number;
+    get duration(): number | null {
+        return this._duration;
     }
 
     /**
@@ -250,34 +275,34 @@ class SoundSlotElement extends AsyncElement {
         return ['asset', 'auto-play', 'duration', 'loop', 'name', 'overlap', 'pitch', 'start-time', 'volume'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'asset':
-                this.asset = newValue;
+                this.asset = newValue ?? '';
                 break;
             case 'auto-play':
-                this.autoPlay = this.hasAttribute('auto-play');
+                this.autoPlay = parseBool(newValue, false);
                 break;
             case 'duration':
-                this.duration = parseFloat(newValue);
+                this.duration = parseNumber(newValue, null, name);
                 break;
             case 'loop':
-                this.loop = this.hasAttribute('loop');
+                this.loop = parseBool(newValue, false);
                 break;
             case 'name':
-                this.name = newValue;
+                this.name = newValue ?? '';
                 break;
             case 'overlap':
-                this.overlap = this.hasAttribute('overlap');
+                this.overlap = parseBool(newValue, false);
                 break;
             case 'pitch':
-                this.pitch = parseFloat(newValue);
+                this.pitch = parseNumber(newValue, 1, name);
                 break;
             case 'start-time':
-                this.startTime = parseFloat(newValue);
+                this.startTime = parseNumber(newValue, 0, name);
                 break;
             case 'volume':
-                this.volume = parseFloat(newValue);
+                this.volume = parseNumber(newValue, 1, name);
                 break;
         }
     }
@@ -285,4 +310,10 @@ class SoundSlotElement extends AsyncElement {
 
 customElements.define('pc-sound', SoundSlotElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sound': SoundSlotElement;
+    }
+}
+
 export { SoundSlotElement };

package/src/entity.ts

@@ -1,13 +1,31 @@
 import { AppBase, Entity, Vec3 } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
-import { parseVec3 } from './utils';
+import { parseBool, parseTags, parseVec3 } from './parse';
 
 /**
  * The EntityElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
  * The EntityElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+ * intersects this entity's geometry. They are only generated while the entity has a listener for
+ * them, registered either with {@link addEventListener} or with the matching inline `onpointer*`
+ * attribute.
+ *
+ * @attribute {string} onpointerenter - Script to run when the pointer moves onto the entity.
+ * @attribute {string} onpointerleave - Script to run when the pointer moves off the entity.
+ * @attribute {string} onpointermove - Script to run when the pointer moves over the entity.
+ * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+ * entity.
+ * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+ * entity.
+ * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
+ * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
+ * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
+ * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
+ * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
  */
 class EntityElement extends AsyncElement {
     /**
@@ -45,76 +63,48 @@ class EntityElement extends AsyncElement {
      */
     private _listeners: { [key: string]: EventListener[] } = {};
 
+    /**
+     * The event types for which an inline `onpointer*` attribute is currently present.
+     */
+    private _inlineHandlerTypes = new Set<string>();
+
     /**
      * Whether the hierarchy has been built for this entity.
      */
     private _built = false;
 
+    private _entity: Entity | null = null;
+
     /**
-     * The PlayCanvas entity instance.
+     * The PlayCanvas entity instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The entity instance.
      */
-    entity: Entity | null = null;
+    get entity(): Entity {
+        return this._entity!;
+    }
 
     createEntity(app: AppBase) {
         // Guard against double creation. When a subtree is inserted at runtime (e.g. cloning a
         // `<template>`), an ancestor's connectedCallback eagerly creates descendant entities; the
         // descendants' own connectedCallbacks would otherwise create them a second time.
-        if (this.entity) {
+        if (this._entity) {
             return;
         }
 
         // Create a new entity
-        this.entity = new Entity(this.getAttribute('name') || this._name, app);
-
-        const enabled = this.getAttribute('enabled');
-        if (enabled) {
-            this.entity.enabled = enabled !== 'false';
-        }
+        const entity = new Entity(this.getAttribute('name') || this._name, app);
+        this._entity = entity;
 
-        const position = this.getAttribute('position');
-        if (position) {
-            this.entity.setLocalPosition(parseVec3(position));
-        }
-
-        const rotation = this.getAttribute('rotation');
-        if (rotation) {
-            this.entity.setLocalEulerAngles(parseVec3(rotation));
-        }
-
-        const scale = this.getAttribute('scale');
-        if (scale) {
-            this.entity.setLocalScale(parseVec3(scale));
-        }
+        entity.enabled = parseBool(this.getAttribute('enabled'), true);
+        entity.setLocalPosition(parseVec3(this.getAttribute('position'), Vec3.ZERO, 'position'));
+        entity.setLocalEulerAngles(parseVec3(this.getAttribute('rotation'), Vec3.ZERO, 'rotation'));
+        entity.setLocalScale(parseVec3(this.getAttribute('scale'), Vec3.ONE, 'scale'));
 
-        const tags = this.getAttribute('tags');
-        if (tags) {
-            this.entity.tags.add(tags.split(',').map(tag => tag.trim()));
+        const tags = parseTags(this.getAttribute('tags'));
+        if (tags.length > 0) {
+            entity.tags.add(tags);
         }
-
-        // Handle pointer events
-        const pointerEvents = [
-            'onpointerenter',
-            'onpointerleave',
-            'onpointerdown',
-            'onpointerup',
-            'onpointermove'
-        ];
-
-        pointerEvents.forEach((eventName) => {
-            const handler = this.getAttribute(eventName);
-            if (handler) {
-                const eventType = eventName.substring(2); // remove 'on' prefix
-                const eventHandler = (event: Event) => {
-                    try {
-                        /* eslint-disable-next-line no-new-func */
-                        new Function('event', handler).call(this, event);
-                    } catch (e) {
-                        console.error('Error in event handler:', e);
-                    }
-                };
-                this.addEventListener(eventType, eventHandler);
-            }
-        });
     }
 
     buildHierarchy(app: AppBase) {
@@ -159,12 +149,12 @@ class EntityElement extends AsyncElement {
             // Notify all children that their entities are about to become invalid
             const children = this.querySelectorAll('pc-entity');
             children.forEach((child) => {
-                (child as EntityElement).entity = null;
+                (child as EntityElement)._entity = null;
             });
 
             // Destroy the entity
             this.entity.destroy();
-            this.entity = null;
+            this._entity = null;
             this._built = false;
         }
     }
@@ -284,6 +274,31 @@ class EntityElement extends AsyncElement {
         return this._tags;
     }
 
+    /**
+     * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+     * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
+     * the previous handler and removing it removes the handler, exactly like `onclick` on any
+     * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
+     * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
+     * kept in sync here.
+     *
+     * @param name - The attribute name (e.g. 'onpointerdown').
+     * @param value - The attribute value, or `null` when the attribute has been removed.
+     */
+    private _updateInlineHandler(name: string, value: string | null) {
+        const type = name.substring(2);
+        const had = this._inlineHandlerTypes.has(type);
+        const has = value !== null;
+
+        if (has && !had) {
+            this._inlineHandlerTypes.add(type);
+            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+        } else if (!has && had) {
+            this._inlineHandlerTypes.delete(type);
+            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+        }
+    }
+
     static get observedAttributes() {
         return [
             'enabled',
@@ -300,45 +315,32 @@ class EntityElement extends AsyncElement {
         ];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'enabled':
-                this.enabled = newValue !== 'false';
+                this.enabled = parseBool(newValue, true);
                 break;
             case 'name':
-                this.name = newValue;
+                this.name = newValue ?? 'Untitled';
                 break;
             case 'position':
-                this.position = parseVec3(newValue);
+                this.position = parseVec3(newValue, Vec3.ZERO, name);
                 break;
             case 'rotation':
-                this.rotation = parseVec3(newValue);
+                this.rotation = parseVec3(newValue, Vec3.ZERO, name);
                 break;
             case 'scale':
-                this.scale = parseVec3(newValue);
+                this.scale = parseVec3(newValue, Vec3.ONE, name);
                 break;
             case 'tags':
-                this.tags = newValue.split(',').map(tag => tag.trim());
+                this.tags = parseTags(newValue);
                 break;
             case 'onpointerenter':
             case 'onpointerleave':
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
-                if (newValue) {
-                    const eventName = name.substring(2);
-                    // Use Function.prototype.bind to avoid new Function
-                    const handler = (event: Event) => {
-                        try {
-                            const handlerStr = this.getAttribute(eventName) || '';
-                            /* eslint-disable-next-line no-new-func */
-                            new Function('event', handlerStr).call(this, event);
-                        } catch (e) {
-                            console.error('Error in event handler:', e);
-                        }
-                    };
-                    this.addEventListener(eventName, handler);
-                }
+                this._updateInlineHandler(name, newValue);
                 break;
         }
     }
@@ -365,10 +367,16 @@ class EntityElement extends AsyncElement {
     }
 
     hasListeners(type: string): boolean {
-        return Boolean(this._listeners[type]?.length);
+        return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
     }
 }
 
 customElements.define('pc-entity', EntityElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-entity': EntityElement;
+    }
+}
+
 export { EntityElement };

package/src/index.ts

@@ -10,7 +10,7 @@
 /* eslint-disable import/order */
 
 // Note that order matters here (e.g. pc-entity must be defined before components)
-import { AsyncElement } from './async-element';
+import { AsyncElement, whenReady } from './async-element';
 import { ModuleElement } from './module';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
@@ -69,5 +69,8 @@ export {
     MaterialElement,
     ModelElement,
     SceneElement,
-    SkyElement
+    SkyElement,
+    whenReady
 };
+
+export type { AsyncElementTagName } from './async-element';