@playcanvas/web-components 0.9.0 → 0.10.1

package/src/entity.ts

@@ -1,13 +1,31 @@
 import { AppBase, Entity, Vec3 } from 'playcanvas';
 
 import { AsyncElement } from './async-element';
-import { parseBool, 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 {
     /**
@@ -58,12 +76,13 @@ class EntityElement extends AsyncElement {
     private _entity: Entity | null = null;
 
     /**
-     * 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.
+     * 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`.
      */
-    get entity(): Entity {
-        return this._entity!;
+    get entity(): Entity | null {
+        return this._entity;
     }
 
     createEntity(app: AppBase) {
@@ -74,18 +93,20 @@ class EntityElement extends AsyncElement {
             return;
         }
 
-        // Create a new entity
-        const entity = new Entity(this.getAttribute('name') || this._name, app);
+        // 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 = 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'));
+        entity.enabled = this._enabled;
+        entity.setLocalPosition(this._position);
+        entity.setLocalEulerAngles(this._rotation);
+        entity.setLocalScale(this._scale);
 
-        const tags = this.getAttribute('tags');
-        if (tags) {
-            entity.tags.add(tags.split(',').map(tag => tag.trim()));
+        if (this._tags.length > 0) {
+            entity.tags.add(this._tags);
         }
     }
 
@@ -106,7 +127,15 @@ class EntityElement extends AsyncElement {
     connectedCallback() {
         // Wait for app to be ready
         const closestApp = this.closestApp;
-        if (!closestApp) return;
+        if (!closestApp) {
+            // An entity outside an application is inert and never becomes ready, so awaiting it
+            // hangs. Warn rather than fail silently, naming the parent it requires, as every other
+            // misplaced element does.
+            const name = this.getAttribute('name');
+            const label = name ? ` '${name}'` : '';
+            console.warn(`pc-entity${label} must be a descendant of pc-app - entity not created`);
+            return;
+        }
 
         // If app is already running, create entity immediately
         if (closestApp.hierarchyReady) {
@@ -128,10 +157,15 @@ class EntityElement extends AsyncElement {
 
     disconnectedCallback() {
         if (this.entity) {
-            // Notify all children that their entities are about to become invalid
-            const children = this.querySelectorAll('pc-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 as EntityElement)._entity = null;
+                child._entity = null;
+                child._built = false;
             });
 
             // Destroy the entity
@@ -297,13 +331,13 @@ 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 = parseBool(newValue, true);
                 break;
             case 'name':
-                this.name = newValue;
+                this.name = newValue ?? 'Untitled';
                 break;
             case 'position':
                 this.position = parseVec3(newValue, Vec3.ZERO, name);
@@ -315,7 +349,7 @@ class EntityElement extends AsyncElement {
                 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':

package/src/loading-bar.ts

@@ -0,0 +1,122 @@
+/** Covers the 0.2s opacity transition; jsdom never fires transitionend, so removal is timed. */
+const REMOVAL_DELAY_MS = 250;
+
+/**
+ * The slim progress bar `<pc-app>` shows while it boots and preloads. An implementation detail of
+ * AppElement rather than a custom element, so its shape can change without a breaking change.
+ *
+ * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
+ * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+ * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+ */
+class LoadingBar {
+    private _track: HTMLDivElement;
+
+    private _fill: HTMLDivElement;
+
+    private _sweep: Animation | null = null;
+
+    private _removal: ReturnType<typeof setTimeout> | null = null;
+
+    /**
+     * Creates the bar and appends it to `parent`, starting in the indeterminate state.
+     * @param parent - The element to append the bar to.
+     */
+    constructor(parent: HTMLElement) {
+        this._track = document.createElement('div');
+        this._track.setAttribute('role', 'progressbar');
+        this._track.setAttribute('aria-label', 'Loading');
+        this._track.setAttribute('aria-valuemin', '0');
+        this._track.setAttribute('aria-valuemax', '100');
+        // Fixed positioning matches the canvas, which always fills the window (FILLMODE_FILL_WINDOW)
+        this._track.style.cssText = [
+            'position: fixed',
+            'top: 0',
+            'left: 0',
+            'width: 100%',
+            'height: var(--pc-loading-bar-height, 3px)',
+            'background: var(--pc-loading-bar-background, rgba(0, 0, 0, 0.1))',
+            'z-index: 10000',
+            'pointer-events: none',
+            'opacity: 1',
+            'transition: opacity 0.2s ease'
+        ].join('; ');
+
+        this._fill = document.createElement('div');
+        this._fill.style.cssText = [
+            'width: 100%',
+            'height: 100%',
+            'transform-origin: left center',
+            'transform: scaleX(0)',
+            'background: var(--pc-loading-bar-color, #f60)',
+            'transition: transform 0.2s ease'
+        ].join('; ');
+
+        this._track.appendChild(this._fill);
+        parent.appendChild(this._track);
+
+        // Indeterminate sweep until the first progress() call reports a real total. No
+        // 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'
+            });
+        }
+    }
+
+    /**
+     * Reflects preload progress, switching the bar from indeterminate to determinate on the first
+     * call.
+     * @param loaded - The number of assets that have finished loading.
+     * @param total - The number of assets being preloaded.
+     */
+    progress(loaded: number, total: number) {
+        if (this._sweep) {
+            this._sweep.cancel();
+            this._sweep = null;
+        }
+        const fraction = total === 0 ? 1 : loaded / total;
+        this._track.setAttribute('aria-valuenow', String(Math.round(fraction * 100)));
+        this._fill.style.transform = `scaleX(${fraction})`;
+    }
+
+    /**
+     * Fills the bar, fades it out and removes it. Idempotent.
+     */
+    complete() {
+        if (this._removal !== null) {
+            return;
+        }
+        if (this._sweep) {
+            this._sweep.cancel();
+            this._sweep = null;
+        }
+        this._track.setAttribute('aria-valuenow', '100');
+        this._fill.style.transform = 'scaleX(1)';
+        this._track.style.opacity = '0';
+        this._removal = setTimeout(() => this._track.remove(), REMOVAL_DELAY_MS);
+    }
+
+    /**
+     * Removes the bar immediately, cancelling any pending fade. Idempotent.
+     */
+    destroy() {
+        if (this._sweep) {
+            this._sweep.cancel();
+            this._sweep = null;
+        }
+        if (this._removal !== null) {
+            clearTimeout(this._removal);
+            this._removal = null;
+        }
+        this._track.remove();
+    }
+}
+
+export { LoadingBar };