@playcanvas/web-components 0.10.1 → 0.11.0

package/src/components/scrollview-component.ts

@@ -99,7 +99,8 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets whether horizontal scrolling is enabled.
+     * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
      * @param value - Whether horizontal scrolling is enabled.
      */
     set horizontal(value: boolean) {
@@ -110,7 +111,7 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets whether horizontal scrolling is enabled.
+     * Gets whether scrolling along the horizontal axis is enabled.
      * @returns Whether horizontal scrolling is enabled.
      */
     get horizontal() {
@@ -118,7 +119,8 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets whether vertical scrolling is enabled.
+     * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
      * @param value - Whether vertical scrolling is enabled.
      */
     set vertical(value: boolean) {
@@ -129,7 +131,7 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical() {

package/src/entity.ts

@@ -1,5 +1,6 @@
 import { AppBase, Entity, Vec3 } from 'playcanvas';
 
+import type { AppElement } from './app';
 import { AsyncElement } from './async-element';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -75,6 +76,12 @@ class EntityElement extends AsyncElement {
 
     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()`
@@ -108,6 +115,29 @@ class EntityElement extends AsyncElement {
         if (this._tags.length > 0) {
             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);
+        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.
+     *
+     * @param entity - The entity that was destroyed.
+     */
+    private _onEntityDestroy(entity: Entity) {
+        this._appElement?._unregisterEntityElement(entity);
+        this._appElement = null;
+        this._entity = null;
+        this._built = false;
     }
 
     buildHierarchy(app: AppBase) {
@@ -156,23 +186,11 @@ class EntityElement extends AsyncElement {
     }
 
     disconnectedCallback() {
-        if (this.entity) {
-            // Notify all children that their entities are about to become invalid. Both fields have
-            // to be reset here, not just _entity: a descendant's own disconnectedCallback runs after
-            // this one and skips its reset behind the `if (this.entity)` guard, because we have
-            // already nulled the entity it tests. Leaving _built set would make buildHierarchy bail
-            // on re-insertion, so the descendant would get a fresh entity that is never parented.
-            const children = this.querySelectorAll<EntityElement>('pc-entity');
-            children.forEach((child) => {
-                child._entity = null;
-                child._built = false;
-            });
-
-            // Destroy the entity
-            this.entity.destroy();
-            this._entity = null;
-            this._built = false;
-        }
+        // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
+        // every entity in it - so _onEntityDestroy resets this element AND every descendant
+        // element before the descendants' own disconnectedCallbacks run. Their entities are null
+        // by then, making this call a no-op for them.
+        this._entity?.destroy();
     }
 
     /**

package/src/parse.ts

@@ -113,21 +113,23 @@ export const parseColor = <T extends Color | null>(value: string | null, default
  * the value is invalid — the latter also logs a warning listing the valid names.
  *
  * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param valid - The valid names: an array, or a map whose keys are the valid names. Only the keys
+ * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
+ * but some (e.g. `SCALEMODE_BLEND`) are strings.
  * @param defaultValue - The value to use when the attribute is absent or invalid.
  * @param attribute - The attribute name, used in the warning message.
  * @returns The resolved enum name.
  */
 export const parseEnum = <T extends string>(
     value: string | null,
-    valid: readonly T[] | ReadonlyMap<T, number>,
+    valid: readonly T[] | ReadonlyMap<T, unknown>,
     defaultValue: T,
     attribute: string
 ): T => {
     if (value === null) {
         return defaultValue;
     }
-    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
+    const names: readonly T[] = Array.isArray(valid) ? valid : [...valid.keys()];
     if (names.includes(value as T)) {
         return value as T;
     }

package/src/sky.ts

@@ -19,7 +19,7 @@ class SkyElement extends AsyncElement {
 
     private _rotation = new Vec3();
 
-    private _level = 0;
+    private _mipLevel = 0;
 
     private _lighting = false;
 
@@ -65,7 +65,7 @@ class SkyElement extends AsyncElement {
         this._scene.sky.node.setLocalScale(this._scale);
         this._scene.sky.center = this._center;
         this._scene.skyboxIntensity = this._intensity;
-        this._scene.skyboxMip = this._level;
+        this._scene.skyboxMip = this._mipLevel;
     }
 
     private async _loadSkybox() {
@@ -170,25 +170,6 @@ class SkyElement extends AsyncElement {
         return this._intensity;
     }
 
-    /**
-     * Sets the mip level of the skybox.
-     * @param value - The mip level.
-     */
-    set level(value: number) {
-        this._level = value;
-        if (this._scene) {
-            this._scene.skyboxMip = this._level;
-        }
-    }
-
-    /**
-     * Gets the mip level of the skybox.
-     * @returns The mip level.
-     */
-    get level() {
-        return this._level;
-    }
-
     /**
      * Sets whether the skybox is used as a light source.
      * @param value - Whether to use lighting.
@@ -205,6 +186,26 @@ class SkyElement extends AsyncElement {
         return this._lighting;
     }
 
+    /**
+     * Sets the mip level of the skybox, where 0 is the sharpest. Raising it selects a blurrier mip,
+     * which is how a skybox is softened without blurring the texture itself.
+     * @param value - The mip level.
+     */
+    set mipLevel(value: number) {
+        this._mipLevel = value;
+        if (this._scene) {
+            this._scene.skyboxMip = this._mipLevel;
+        }
+    }
+
+    /**
+     * Gets the mip level of the skybox.
+     * @returns The mip level.
+     */
+    get mipLevel() {
+        return this._mipLevel;
+    }
+
     /**
      * Sets the Euler rotation of the skybox.
      * @param value - The rotation.
@@ -267,7 +268,7 @@ class SkyElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
+        return ['asset', 'center', 'intensity', 'lighting', 'mip-level', 'rotation', 'scale', 'type'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -281,12 +282,12 @@ class SkyElement extends AsyncElement {
             case 'intensity':
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
-            case 'level':
-                this.level = parseNumber(newValue, 0, name);
-                break;
             case 'lighting':
                 this.lighting = parseBool(newValue, false);
                 break;
+            case 'mip-level':
+                this.mipLevel = parseNumber(newValue, 0, name);
+                break;
             case 'rotation':
                 this.rotation = parseVec3(newValue, Vec3.ZERO, name);
                 break;