@playcanvas/web-components 0.8.1 → 0.9.0

package/src/entity.ts

@@ -1,7 +1,7 @@
 import { AppBase, Entity, Vec3 } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
-import { parseVec3 } from './utils';
+import { parseBool, parseVec3 } from './utils';
 
 /**
  * The EntityElement interface provides properties and methods for manipulating
@@ -45,76 +45,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()));
+            entity.tags.add(tags.split(',').map(tag => tag.trim()));
         }
-
-        // 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 +131,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 +256,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',
@@ -303,19 +300,19 @@ class EntityElement extends AsyncElement {
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         switch (name) {
             case 'enabled':
-                this.enabled = newValue !== 'false';
+                this.enabled = parseBool(newValue, true);
                 break;
             case 'name':
                 this.name = newValue;
                 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());
@@ -325,20 +322,7 @@ class EntityElement extends AsyncElement {
             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 +349,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';

package/src/material.ts

@@ -1,5 +1,6 @@
 import { Color, StandardMaterial, Texture } from 'playcanvas';
 
+import { AppElement } from './app';
 import { AssetElement } from './asset';
 import { parseColor } from './utils';
 
@@ -8,6 +9,10 @@ import { parseColor } from './utils';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
  * The MaterialElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * A `pc-material` must be a direct child of `pc-app` — elements placed elsewhere log a warning
+ * and never create a material. Elements inserted while the application is already running are
+ * created on insertion.
  */
 class MaterialElement extends HTMLElement {
     private _diffuse = new Color(1, 1, 1);
@@ -22,6 +27,28 @@ class MaterialElement extends HTMLElement {
 
     material: StandardMaterial | null = null;
 
+    async connectedCallback() {
+        const appElement = this.parentElement?.closest('pc-app') as AppElement | null ?? null;
+
+        // Materials must be direct children of pc-app (matches the boot query ':scope > pc-material')
+        if (!appElement || this.parentElement !== appElement) {
+            console.warn(`pc-material '${this.id}' must be a direct child of pc-app - material not created`);
+            return;
+        }
+
+        await appElement.ready();
+
+        // The element may have been removed or re-parented while waiting for the app
+        if (!this.isConnected || this.parentElement !== appElement) return;
+
+        // Materials present at startup are created by AppElement's boot; this branch handles
+        // elements inserted (or re-inserted) after the app is already running
+        if (!this.material) {
+            if (!appElement.app) return; // pc-app is re-connecting; its own boot will create this
+            this.createMaterial();
+        }
+    }
+
     createMaterial() {
         this.material = new StandardMaterial();
         this.material.glossInvert = false;
@@ -118,7 +145,7 @@ class MaterialElement extends HTMLElement {
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         switch (name) {
             case 'diffuse':
-                this.diffuse = parseColor(newValue);
+                this.diffuse = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'diffuse-map':
                 this.diffuseMap = newValue;
@@ -138,4 +165,10 @@ class MaterialElement extends HTMLElement {
 
 customElements.define('pc-material', MaterialElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-material': MaterialElement;
+    }
+}
+
 export { MaterialElement };

package/src/model.ts

@@ -108,4 +108,10 @@ class ModelElement extends AsyncElement {
 
 customElements.define('pc-model', ModelElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-model': ModelElement;
+    }
+}
+
 export { ModelElement };

package/src/module.ts

@@ -40,4 +40,10 @@ class ModuleElement extends HTMLElement {
 
 customElements.define('pc-module', ModuleElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-module': ModuleElement;
+    }
+}
+
 export { ModuleElement };

package/src/scene.ts

@@ -2,7 +2,7 @@ import { Color, Scene, Vec3 } from 'playcanvas';
 
 import { AppElement } from './app';
 import { AsyncElement } from './async-element';
-import { parseColor, parseVec3 } from './utils';
+import { parseColor, parseEnum, parseNumber, parseVec3 } from './utils';
 
 /**
  * The SceneElement interface provides properties and methods for manipulating
@@ -14,7 +14,7 @@ class SceneElement extends AsyncElement {
     /**
      * The fog type of the scene.
      */
-    private _fog = 'none'; // possible values: 'none', 'linear', 'exp', 'exp2'
+    private _fog: 'none' | 'linear' | 'exp' | 'exp2' = 'none';
 
     /**
      * The color of the fog.
@@ -41,15 +41,21 @@ class SceneElement extends AsyncElement {
      */
     private _gravity = new Vec3(0, -9.81, 0);
 
+    private _scene: Scene | null = null;
+
     /**
-     * The PlayCanvas scene instance.
+     * The PlayCanvas scene instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The scene instance.
      */
-    scene: Scene | null = null;
+    get scene(): Scene {
+        return this._scene!;
+    }
 
     async connectedCallback() {
         await this.closestApp?.ready();
 
-        this.scene = this.closestApp!.app!.scene;
+        this._scene = this.closestApp!.app!.scene;
         this.updateSceneSettings();
 
         this._onReady();
@@ -69,7 +75,8 @@ class SceneElement extends AsyncElement {
     }
 
     /**
-     * Sets the fog type of the scene.
+     * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
+     * `none`.
      * @param value - The fog type.
      */
     set fog(value) {
@@ -190,22 +197,22 @@ class SceneElement extends AsyncElement {
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         switch (name) {
             case 'fog':
-                this.fog = newValue;
+                this.fog = parseEnum(newValue, ['none', 'linear', 'exp', 'exp2'], 'none', name);
                 break;
             case 'fog-color':
-                this.fogColor = parseColor(newValue);
+                this.fogColor = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'fog-density':
-                this.fogDensity = parseFloat(newValue);
+                this.fogDensity = parseNumber(newValue, 0, name);
                 break;
             case 'fog-start':
-                this.fogStart = parseFloat(newValue);
+                this.fogStart = parseNumber(newValue, 0, name);
                 break;
             case 'fog-end':
-                this.fogEnd = parseFloat(newValue);
+                this.fogEnd = parseNumber(newValue, 1000, name);
                 break;
             case 'gravity':
-                this.gravity = parseVec3(newValue);
+                this.gravity = parseVec3(newValue, new Vec3(0, -9.81, 0), name);
                 break;
             // ... handle other attributes as well
         }
@@ -214,4 +221,10 @@ class SceneElement extends AsyncElement {
 
 customElements.define('pc-scene', SceneElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scene': SceneElement;
+    }
+}
+
 export { SceneElement };

package/src/sky.ts

@@ -1,8 +1,9 @@
 import { Asset, EnvLighting, LAYERID_SKYBOX, Quat, Scene, Texture, Vec3 } from 'playcanvas';
 
+import { AppElement } from './app';
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
-import { parseVec3 } from './utils';
+import { parseBool, parseEnum, parseNumber, parseVec3 } from './utils';
 
 /**
  * The SkyElement interface provides properties and methods for manipulating
@@ -28,6 +29,8 @@ class SkyElement extends AsyncElement {
 
     private _scene: Scene | null = null;
 
+    private _appElement: AppElement | null = null;
+
     connectedCallback() {
         this._loadSkybox();
         this._onReady();
@@ -35,6 +38,7 @@ class SkyElement extends AsyncElement {
 
     disconnectedCallback() {
         this._unloadSkybox();
+        this._appElement = null;
     }
 
     private _generateSkybox(asset: Asset) {
@@ -67,10 +71,12 @@ class SkyElement extends AsyncElement {
     private async _loadSkybox() {
         const appElement = await this.closestApp?.ready();
         const app = appElement?.app;
-        if (!app) {
+        if (!appElement || !app) {
             return;
         }
 
+        this._appElement = appElement;
+
         const asset = AssetElement.get(this._asset);
         if (!asset) {
             return;
@@ -89,16 +95,22 @@ class SkyElement extends AsyncElement {
     }
 
     private _unloadSkybox() {
-        if (!this._scene) return;
+        const scene = this._scene;
+        if (!scene) return;
+
+        this._scene = null;
+
+        // If the owning application has already been destroyed (removing a <pc-app>
+        // disconnects it before its children), the scene, graphics device and skybox
+        // textures have all been destroyed along with it — nothing left to clean up.
+        if (!this._appElement?.app) return;
 
-        this._scene.skybox?.destroy();
+        scene.skybox?.destroy();
         // @ts-ignore
-        this._scene.skybox = null;
-        this._scene.envAtlas?.destroy();
+        scene.skybox = null;
+        scene.envAtlas?.destroy();
         // @ts-ignore
-        this._scene.envAtlas = null;
-
-        this._scene = null;
+        scene.envAtlas = null;
     }
 
     /**
@@ -264,25 +276,25 @@ class SkyElement extends AsyncElement {
                 this.asset = newValue;
                 break;
             case 'center':
-                this.center = parseVec3(newValue);
+                this.center = parseVec3(newValue, new Vec3(0, 0.01, 0), name);
                 break;
             case 'intensity':
-                this.intensity = parseFloat(newValue);
+                this.intensity = parseNumber(newValue, 1, name);
                 break;
             case 'level':
-                this.level = parseInt(newValue, 10);
+                this.level = parseNumber(newValue, 0, name);
                 break;
             case 'lighting':
-                this.lighting = this.hasAttribute(name);
+                this.lighting = parseBool(newValue, false);
                 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, new Vec3(100, 100, 100), name);
                 break;
             case 'type':
-                this.type = newValue as 'box' | 'dome' | 'infinite' | 'none';
+                this.type = parseEnum(newValue, ['box', 'dome', 'infinite', 'none'], 'infinite', name);
                 break;
         }
     }
@@ -290,4 +302,10 @@ class SkyElement extends AsyncElement {
 
 customElements.define('pc-sky', SkyElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sky': SkyElement;
+    }
+}
+
 export { SkyElement };