@playcanvas/web-components 0.11.0 → 0.12.0

package/src/entity-base.ts

@@ -0,0 +1,136 @@
+import type { Entity } from 'playcanvas';
+
+import type { AppElement } from './app';
+import { AsyncElement } from './async-element';
+
+/**
+ * The attribute names of the inline `onpointer*` event handlers, shared by every element that
+ * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * @ignore
+ */
+const POINTER_ATTRIBUTES = [
+    'onpointerenter',
+    'onpointerleave',
+    'onpointerdown',
+    'onpointerup',
+    'onpointermove'
+] as const;
+
+/**
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
+ * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
+ * what both need — the `entity` contract, registration with the owning application (which joins
+ * picked scene nodes back to elements by identity, never by name), and the pointer listener
+ * bookkeeping that lets the application lazily attach its canvas handlers.
+ */
+class EntityBaseElement extends AsyncElement {
+    protected _entity: Entity | null = null;
+
+    /**
+     * The application element this entity is registered with, cached at registration time so the
+     * entity can be unregistered even once this element has left the DOM.
+     */
+    protected _appElement: AppElement | null = null;
+
+    /**
+     * The pointer event listeners for the entity.
+     */
+    private _listeners: Record<string, EventListener[]> = {};
+
+    /**
+     * The event types for which an inline `onpointer*` attribute is currently present.
+     */
+    private _inlineHandlerTypes = new Set<string>();
+
+    /**
+     * The PlayCanvas entity instance. `null` until the element is ready, and again once the
+     * entity is gone — await {@link whenReady} or the element's `ready()` promise before
+     * accessing it.
+     * @returns The entity instance, or `null`.
+     */
+    get entity(): Entity | null {
+        return this._entity;
+    }
+
+    /**
+     * Registers `entity` as this element's backing entity with the owning application, which
+     * joins engine nodes back to elements by identity (never by name).
+     *
+     * @param entity - The entity to register.
+     */
+    protected _registerEntity(entity: Entity) {
+        this._appElement = this.closestApp;
+        this._appElement?._registerEntityElement(entity, this);
+    }
+
+    /**
+     * Removes the registration for `entity`.
+     *
+     * @param entity - The entity to unregister.
+     */
+    protected _unregisterEntity(entity: Entity) {
+        this._appElement?._unregisterEntityElement(entity);
+        this._appElement = null;
+    }
+
+    /**
+     * 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.
+     */
+    protected _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 }));
+        }
+    }
+
+    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions) {
+        if (!this._listeners[type]) {
+            this._listeners[type] = [];
+        }
+        this._listeners[type].push(listener);
+        super.addEventListener(type, listener, options);
+        if (type.startsWith('pointer')) {
+            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+        }
+    }
+
+    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions) {
+        if (this._listeners[type]) {
+            this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
+        }
+        super.removeEventListener(type, listener, options);
+        if (type.startsWith('pointer')) {
+            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+        }
+    }
+
+    /**
+     * Whether the element has a listener for an event type, registered either with
+     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+     * containing `<pc-app>` element to gate pointer event synthesis.
+     *
+     * @param type - The event type.
+     * @returns Whether a listener is registered.
+     * @internal
+     */
+    _hasListeners(type: string): boolean {
+        return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
+    }
+}
+
+export { EntityBaseElement, POINTER_ATTRIBUTES };

package/src/entity.ts

@@ -1,7 +1,7 @@
-import { AppBase, Entity, Vec3 } from 'playcanvas';
+import type { AppBase } from 'playcanvas';
+import { Entity, Vec3 } from 'playcanvas';
 
-import type { AppElement } from './app';
-import { AsyncElement } from './async-element';
+import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
 /**
@@ -28,7 +28,7 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * @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 {
+class EntityElement extends EntityBaseElement {
     /**
      * Whether the entity is enabled.
      */
@@ -59,40 +59,19 @@ class EntityElement extends AsyncElement {
      */
     private _tags: string[] = [];
 
-    /**
-     * The pointer event listeners for the entity.
-     */
-    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 application element this entity is registered with, cached at creation time so the
-     * entity can be unregistered even once this element has left the DOM.
-     */
-    private _appElement: AppElement | null = null;
-
-    /**
-     * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
-     * been removed from the document — await {@link whenReady} or the element's `ready()`
-     * promise before accessing it.
-     * @returns The entity instance, or `null`.
+     * Creates the backing entity. Called by the containing `<pc-app>` element during its boot
+     * sweep, and on connection for elements inserted while the application is already running.
+     *
+     * @param app - The application to create the entity in.
+     * @internal
      */
-    get entity(): Entity | null {
-        return this._entity;
-    }
-
-    createEntity(app: AppBase) {
+    _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.
@@ -116,35 +95,53 @@ class EntityElement extends AsyncElement {
             entity.tags.add(this._tags);
         }
 
-        // Register with the owning application, which joins engine nodes back to elements by
-        // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
-        // for every entity in a destroyed subtree, so the element learns of its entity's death no
-        // matter who causes it: this element, an ancestor, the whole application, or a user
-        // script calling entity.destroy().
-        this._appElement = this.closestApp;
-        this._appElement?._registerEntityElement(entity, this);
+        // Register with the owning application and hook the entity's destruction. The engine
+        // fires 'destroy' for every entity in a destroyed subtree, so the element learns of its
+        // entity's death no matter who causes it: this element, an ancestor, the whole
+        // application, or a user script calling entity.destroy().
+        this._registerEntity(entity);
         entity.once('destroy', this._onEntityDestroy, this);
     }
 
     /**
      * Handles the destruction of the backing entity. Resets the element so a later re-insertion
-     * starts clean: `_built` must be cleared alongside `_entity`, or buildHierarchy would bail
-     * and a re-created entity would never be parented.
+     * starts clean: `_built` must be cleared alongside `_entity`, or _buildHierarchy would bail
+     * and a re-created entity would never be parented. Readiness is re-armed for the same
+     * reason — with the entity gone, a resolved ready promise would resume its awaiters against
+     * a null `entity`.
      *
      * @param entity - The entity that was destroyed.
      */
     private _onEntityDestroy(entity: Entity) {
-        this._appElement?._unregisterEntityElement(entity);
-        this._appElement = null;
+        this._unregisterEntity(entity);
         this._entity = null;
         this._built = false;
+        this._resetReady();
     }
 
-    buildHierarchy(app: AppBase) {
+    /**
+     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` or
+     * `<pc-node>` when there is one, and under the application root otherwise. Called by the
+     * containing `<pc-app>` element once a sweep has created every entity, so a parent's
+     * existence never depends on document order.
+     *
+     * @param app - The application whose root adopts parentless entities.
+     * @internal
+     */
+    _buildHierarchy(app: AppBase) {
         if (!this.entity || this._built) return;
-        this._built = true;
 
         const closestEntity = this.closestEntity;
+
+        // A host element without an entity is an unresolved `<pc-node>`: building now would
+        // mis-anchor this entity to the application root while the host is still resolving.
+        // Stay unbuilt - the host drives this subtree itself once it binds.
+        if (closestEntity && !closestEntity.entity) {
+            return;
+        }
+
+        this._built = true;
+
         if (closestEntity?.entity) {
             closestEntity.entity.addChild(this.entity);
         } else {
@@ -168,19 +165,19 @@ class EntityElement extends AsyncElement {
         }
 
         // If app is already running, create entity immediately
-        if (closestApp.hierarchyReady) {
+        if (closestApp._hierarchyReady) {
             const app = closestApp.app!;
 
-            this.createEntity(app);
-            this.buildHierarchy(app);
+            this._createEntity(app);
+            this._buildHierarchy(app);
 
             // Handle any child entities that might exist
             const childEntities = this.querySelectorAll<EntityElement>('pc-entity');
             childEntities.forEach((child) => {
-                child.createEntity(app);
+                child._createEntity(app);
             });
             childEntities.forEach((child) => {
-                child.buildHierarchy(app);
+                child._buildHierarchy(app);
             });
         }
     }
@@ -308,45 +305,8 @@ 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',
-            'name',
-            'position',
-            'rotation',
-            'scale',
-            'tags',
-            'onpointerenter',
-            'onpointerleave',
-            'onpointerdown',
-            'onpointerup',
-            'onpointermove'
-        ];
+        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -378,39 +338,8 @@ class EntityElement extends AsyncElement {
                 break;
         }
     }
-
-    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions) {
-        if (!this._listeners[type]) {
-            this._listeners[type] = [];
-        }
-        this._listeners[type].push(listener);
-        super.addEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
-            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-        }
-    }
-
-    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions) {
-        if (this._listeners[type]) {
-            this._listeners[type] = this._listeners[type].filter(l => l !== listener);
-        }
-        super.removeEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
-            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-        }
-    }
-
-    hasListeners(type: string): boolean {
-        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

@@ -7,7 +7,7 @@
  * @module EngineWebComponents
  */
 
-/* eslint-disable import/order */
+/* eslint-disable import-x/order */
 
 // Note that order matters here (e.g. pc-entity must be defined before components)
 import { AsyncElement, whenReady } from './async-element';
@@ -35,11 +35,58 @@ import { ScriptElement } from './components/script';
 import { SoundComponentElement } from './components/sound-component';
 import { SoundSlotElement } from './components/sound-slot';
 import { GSplatComponentElement } from './components/gsplat-component';
+import { EntityBaseElement } from './entity-base';
 import { MaterialElement } from './material';
 import { ModelElement } from './model';
+import { NodeElement } from './node';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
 
+import type {
+    ScriptAttributesChangeEvent,
+    ScriptEnableChangeEvent,
+    ScriptNameChangeEvent
+} from './components/script-component';
+
+declare global {
+    interface HTMLElementEventMap {
+        scriptattributeschange: ScriptAttributesChangeEvent;
+        scriptenablechange: ScriptEnableChangeEvent;
+        scriptnamechange: ScriptNameChangeEvent;
+    }
+
+    interface HTMLElementTagNameMap {
+        'pc-app': AppElement;
+        'pc-asset': AssetElement;
+        'pc-button': ButtonComponentElement;
+        'pc-camera': CameraComponentElement;
+        'pc-collision': CollisionComponentElement;
+        'pc-element': ElementComponentElement;
+        'pc-entity': EntityElement;
+        'pc-gsplat': GSplatComponentElement;
+        'pc-layoutchild': LayoutChildComponentElement;
+        'pc-layoutgroup': LayoutGroupComponentElement;
+        'pc-light': LightComponentElement;
+        'pc-listener': ListenerComponentElement;
+        'pc-material': MaterialElement;
+        'pc-model': ModelElement;
+        'pc-module': ModuleElement;
+        'pc-node': NodeElement;
+        'pc-particles': ParticleSystemComponentElement;
+        'pc-render': RenderComponentElement;
+        'pc-rigidbody': RigidBodyComponentElement;
+        'pc-scene': SceneElement;
+        'pc-screen': ScreenComponentElement;
+        'pc-script': ScriptElement;
+        'pc-scripts': ScriptComponentElement;
+        'pc-scrollbar': ScrollbarComponentElement;
+        'pc-scrollview': ScrollViewComponentElement;
+        'pc-sky': SkyElement;
+        'pc-sound': SoundSlotElement;
+        'pc-sounds': SoundComponentElement;
+    }
+}
+
 export {
     AsyncElement,
     ModuleElement,
@@ -66,8 +113,10 @@ export {
     SoundComponentElement,
     SoundSlotElement,
     GSplatComponentElement,
+    EntityBaseElement,
     MaterialElement,
     ModelElement,
+    NodeElement,
     SceneElement,
     SkyElement,
     whenReady

package/src/loading-bar.ts

@@ -59,14 +59,14 @@ class LoadingBar {
         // aria-valuenow is set, which is what marks a progressbar indeterminate. jsdom has no Web
         // Animations API, so the guard degrades to a static bar there rather than crashing boot.
         if (typeof this._fill.animate === 'function') {
-            this._sweep = this._fill.animate([
-                { transform: 'scaleX(0.25) translateX(-100%)' },
-                { transform: 'scaleX(0.25) translateX(500%)' }
-            ], {
-                duration: 1000,
-                iterations: Infinity,
-                easing: 'ease-in-out'
-            });
+            this._sweep = this._fill.animate(
+                [{ transform: 'scaleX(0.25) translateX(-100%)' }, { transform: 'scaleX(0.25) translateX(500%)' }],
+                {
+                    duration: 1000,
+                    iterations: Infinity,
+                    easing: 'ease-in-out'
+                }
+            );
         }
     }