@playcanvas/web-components 0.15.0 → 0.17.0

package/src/components/{scrollview-component.ts → scroll-view-component.ts}

@@ -25,10 +25,12 @@ const visibilities = new Map<'always' | 'when-required', number>([
 
 /**
  * The ScrollViewComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scrollview/ | `<pc-scrollview>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-scroll-view/ | `<pc-scroll-view>`} elements.
  * The ScrollViewComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollViewComponent} (`scrollview`).
+ *
  * @category Components
  */
 class ScrollViewComponentElement extends ComponentElement {
@@ -437,6 +439,6 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-scrollview', ScrollViewComponentElement);
+customElements.define('pc-scroll-view', ScrollViewComponentElement);
 
 export { ScrollViewComponentElement };

package/src/components/scrollbar-component.ts

@@ -16,6 +16,8 @@ const orientations = new Map<'horizontal' | 'vertical', number>([
  * The ScrollbarComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScrollbarComponent} (`scrollbar`).
+ *
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {

package/src/components/sound-component.ts

@@ -6,10 +6,12 @@ import { ComponentElement } from './component';
 
 /**
  * The SoundComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sounds/ | `<pc-sounds>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sound/ | `<pc-sound>`} elements.
  * The SoundComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link SoundComponent} (`sound`).
+ *
  * @category Components
  */
 class SoundComponentElement extends ComponentElement {
@@ -227,6 +229,6 @@ class SoundComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-sounds', SoundComponentElement);
+customElements.define('pc-sound', SoundComponentElement);
 
 export { SoundComponentElement };

package/src/components/sound-slot.ts

@@ -8,7 +8,7 @@ import { SoundComponentElement } from './sound-component';
 
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
- * `<pc-sound>` elements. The SoundSlotElement interface also inherits the properties and
+ * `<pc-sound-slot>` elements. The SoundSlotElement interface also inherits the properties and
  * methods of the {@link AsyncElement} interface.
  */
 class SoundSlotElement extends AsyncElement {
@@ -31,7 +31,7 @@ class SoundSlotElement extends AsyncElement {
     private _volume = 1;
 
     /**
-     * The `<pc-sounds>` this slot was added to, captured at connect time.
+     * The `<pc-sound>` 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
@@ -106,7 +106,7 @@ class SoundSlotElement extends AsyncElement {
         const soundElement = this.parentElement as SoundComponentElement;
 
         if (!(soundElement instanceof SoundComponentElement)) {
-            console.warn('pc-sound must be a direct child of a pc-sounds element');
+            console.warn('pc-sound-slot must be a direct child of a pc-sound element');
             return null;
         }
 
@@ -324,6 +324,6 @@ class SoundSlotElement extends AsyncElement {
     }
 }
 
-customElements.define('pc-sound', SoundSlotElement);
+customElements.define('pc-sound-slot', SoundSlotElement);
 
 export { SoundSlotElement };

package/src/entity-base.ts

@@ -17,11 +17,12 @@ export const POINTER_ATTRIBUTES = [
 ] 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.
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
+ * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
+ * instantiated hierarchy. It carries what all of them 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;

package/src/entity-owner.ts

@@ -0,0 +1,298 @@
+import type { AppBase } from 'playcanvas';
+import { Entity, Vec3 } from 'playcanvas';
+
+import { EntityBaseElement } from './entity-base';
+
+/**
+ * Creates and parents the entities of every descendant entity-owning element of `root`, in two
+ * passes so that no parent's existence depends on document order. Called wherever a subtree could
+ * not build itself: an element inserted into an application that is already running, and a
+ * `<pc-node>` whose children waited for it to bind.
+ *
+ * Descendants that are not yet custom elements are skipped, because there is nothing useful to do
+ * for them and reaching for `_createEntity` would throw. A subtree cloned from a `<template>`
+ * arrives entirely unupgraded — template content lives in an inert document, where custom element
+ * definitions are never looked up — and appending the clone upgrades its elements in tree order,
+ * an element before its descendants. So a sweep from an element's own `connectedCallback` sees
+ * plain `HTMLElement`s below it. Each becomes an entity-owning element moments later and its own
+ * `connectedCallback` creates and parents it, by which time the ancestor it parents under has its
+ * entity — the same guarantee tree order gives this sweep.
+ *
+ * @param root - The element whose descendant entities to build.
+ * @param app - The application to create the entities in.
+ * @internal
+ */
+export const buildDescendantEntities = (root: Element, app: AppBase) => {
+    const children = Array.from(root.querySelectorAll('pc-entity, pc-model')).filter(
+        (child): child is EntityOwnerElement => child instanceof EntityOwnerElement
+    );
+    children.forEach((child) => child._createEntity(app));
+    children.forEach((child) => child._buildHierarchy(app));
+};
+
+/**
+ * The base class for elements that create and own their backing entity: `<pc-entity>` and
+ * `<pc-model>`, whose host entity carries the same authored properties. It carries the cached
+ * property state, entity creation and parenting, and the reset that follows the entity's
+ * destruction. `<pc-node>` sits outside this class: it borrows an entity a model instantiated,
+ * and its properties are nullable overrides rather than owned values.
+ */
+class EntityOwnerElement extends EntityBaseElement {
+    /**
+     * Whether the entity is enabled.
+     */
+    private _enabled = true;
+
+    /**
+     * The name of the entity.
+     */
+    private _name = 'Untitled';
+
+    /**
+     * The position of the entity.
+     */
+    private _position = new Vec3();
+
+    /**
+     * The rotation of the entity.
+     */
+    private _rotation = new Vec3();
+
+    /**
+     * The scale of the entity.
+     */
+    private _scale = new Vec3(1, 1, 1);
+
+    /**
+     * The tags of the entity.
+     */
+    private _tags: string[] = [];
+
+    /**
+     * Whether the hierarchy has been built for this entity — set once {@link _buildHierarchy} has
+     * parented it. Read by subclasses that gate work on the entity being in the scene graph.
+     */
+    protected _built = false;
+
+    /**
+     * 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
+     */
+    _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) {
+            return;
+        }
+
+        // Seed from the cached fields rather than re-reading the attributes. Every observed
+        // attribute is routed through its property setter by attributeChangedCallback, so the field
+        // already holds the parsed attribute value - and it also holds anything assigned through the
+        // property API before the app booted, which reading the attribute back would discard.
+        const entity = new Entity(this._name, app);
+        this._entity = entity;
+
+        entity.enabled = this._enabled;
+        entity.setLocalPosition(this._position);
+        entity.setLocalEulerAngles(this._rotation);
+        entity.setLocalScale(this._scale);
+
+        if (this._tags.length > 0) {
+            entity.tags.add(this._tags);
+        }
+
+        // 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. 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.
+     */
+    protected _onEntityDestroy(entity: Entity) {
+        this._unregisterEntity(entity);
+        this._entity = null;
+        this._built = false;
+        this._resetReady();
+    }
+
+    /**
+     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>`,
+     * `<pc-model>` 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;
+
+        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;
+        }
+
+        // An owner that exists but is not yet parented is itself deferred behind an unresolved
+        // node further up. Building beneath it would announce readiness for an entity that is
+        // not in the scene graph; stay unbuilt with it - the node's bind sweeps the whole
+        // subtree, ancestors before descendants.
+        if (closestEntity instanceof EntityOwnerElement && !closestEntity._built) {
+            return;
+        }
+
+        this._built = true;
+
+        if (closestEntity?.entity) {
+            closestEntity.entity.addChild(this.entity);
+        } else {
+            app.root.addChild(this.entity);
+        }
+
+        this._onBuilt();
+    }
+
+    /**
+     * Called by {@link _buildHierarchy} once the backing entity has been parented — exactly once
+     * per build cycle. The default announces readiness, which is what a parented `<pc-entity>`
+     * means; `<pc-model>` overrides it to start loading content instead, because its readiness
+     * tracks the content settling rather than the host entering the scene graph.
+     */
+    protected _onBuilt() {
+        this._onReady();
+    }
+
+    /**
+     * Sets the enabled state of the entity.
+     * @param value - Whether the entity is enabled.
+     */
+    set enabled(value) {
+        this._enabled = value;
+        if (this.entity) {
+            this.entity.enabled = value;
+        }
+    }
+
+    /**
+     * Gets the enabled state of the entity.
+     * @returns Whether the entity is enabled.
+     */
+    get enabled() {
+        return this._enabled;
+    }
+
+    /**
+     * Sets the name of the entity.
+     * @param value - The name of the entity.
+     */
+    set name(value) {
+        this._name = value;
+        if (this.entity) {
+            this.entity.name = value;
+        }
+    }
+
+    /**
+     * Gets the name of the entity.
+     * @returns The name of the entity.
+     */
+    get name() {
+        return this._name;
+    }
+
+    /**
+     * Sets the position of the entity.
+     * @param value - The position of the entity.
+     */
+    set position(value) {
+        this._position = value;
+        if (this.entity) {
+            this.entity.setLocalPosition(this._position);
+        }
+    }
+
+    /**
+     * Gets the position of the entity.
+     * @returns The position of the entity.
+     */
+    get position() {
+        return this._position;
+    }
+
+    /**
+     * Sets the rotation of the entity.
+     * @param value - The rotation of the entity.
+     */
+    set rotation(value) {
+        this._rotation = value;
+        if (this.entity) {
+            this.entity.setLocalEulerAngles(this._rotation);
+        }
+    }
+
+    /**
+     * Gets the rotation of the entity.
+     * @returns The rotation of the entity.
+     */
+    get rotation() {
+        return this._rotation;
+    }
+
+    /**
+     * Sets the scale of the entity.
+     * @param value - The scale of the entity.
+     */
+    set scale(value) {
+        this._scale = value;
+        if (this.entity) {
+            this.entity.setLocalScale(this._scale);
+        }
+    }
+
+    /**
+     * Gets the scale of the entity.
+     * @returns The scale of the entity.
+     */
+    get scale() {
+        return this._scale;
+    }
+
+    /**
+     * Sets the tags of the entity.
+     * @param value - The tags of the entity.
+     */
+    set tags(value) {
+        this._tags = value;
+        if (this.entity) {
+            this.entity.tags.clear();
+            this.entity.tags.add(this._tags);
+        }
+    }
+
+    /**
+     * Gets the tags of the entity.
+     * @returns The tags of the entity.
+     */
+    get tags() {
+        return this._tags;
+    }
+}
+
+export { EntityOwnerElement };