@playcanvas/web-components 0.10.0 → 0.10.1

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 };

package/src/material.ts

@@ -114,8 +114,14 @@ type TextureSlot = 'aoMap' | 'diffuseMap' | 'emissiveMap' | 'glossMap' | 'height
  * created on insertion.
  *
  * The element is metal/rough by default: unlike a bare `StandardMaterial` it enables the metalness
- * workflow, which is what the `metalness-*` attributes assume and what glTF means by PBR. The
- * `roughness` and `roughness-map` attributes are aliases for `gloss` and `gloss-map` that
+ * workflow, which is what the `metalness-*` attributes assume and what glTF means by PBR. It also
+ * defaults `metalness` to 0 rather than the engine's 1, because those two defaults have to be
+ * chosen together - the engine's 1 is unreachable under its own `useMetalness` of false, and with
+ * the workflow on it would make every material fully metallic, so `<pc-material diffuse="crimson">`
+ * would render as dark tinted reflections of an environment that may not exist rather than as a
+ * crimson surface. `metalness="1"` remains one attribute away.
+ *
+ * The `roughness` and `roughness-map` attributes are aliases for `gloss` and `gloss-map` that
  * additionally invert the gloss channel; do not mix the two families on one element.
  *
  * The two aliases are documented here rather than on an accessor, because they resolve to the
@@ -222,7 +228,7 @@ class MaterialElement extends HTMLElement {
 
     private _heightMapUv = 0;
 
-    private _metalness = 1;
+    private _metalness = 0;
 
     private _metalnessMap = '';
 
@@ -2386,7 +2392,7 @@ class MaterialElement extends HTMLElement {
                 this.heightMapUv = parseNumber(newValue, 0, name);
                 break;
             case 'metalness':
-                this.metalness = parseNumber(newValue, 1, name);
+                this.metalness = parseNumber(newValue, 0, name);
                 break;
             case 'metalness-map':
                 this.metalnessMap = newValue ?? '';

package/src/scene.ts

@@ -1,6 +1,5 @@
 import { Color, Scene, Vec3 } from 'playcanvas';
 
-import { AppElement } from './app';
 import { AsyncElement } from './async-element';
 import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
 
@@ -44,36 +43,68 @@ class SceneElement extends AsyncElement {
     private _scene: Scene | null = null;
 
     /**
-     * The PlayCanvas scene instance. Available once the element is ready — await
+     * The PlayCanvas scene instance. `null` until the element is ready — await
      * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The scene instance.
+     * @returns The scene instance, or `null`.
      */
-    get scene(): Scene {
-        return this._scene!;
+    get scene(): Scene | null {
+        return this._scene;
     }
 
     async connectedCallback() {
-        await this.closestApp?.ready();
+        const appElement = this.closestApp;
+        if (!appElement) {
+            console.warn('pc-scene must be a descendant of pc-app - scene settings not applied');
+            return;
+        }
+
+        await appElement.ready();
+
+        // The element may have been removed or re-parented while waiting for the app. Matches the
+        // guard in AssetElement and MaterialElement, but compares closestApp rather than
+        // parentElement because pc-scene resolves its app by ancestor rather than direct child.
+        // Without this, a scene re-parented mid-await would take its Scene from the app it started
+        // under while _applyGravity resolved the app it ended up under, splitting the two.
+        if (!this.isConnected || this.closestApp !== appElement) {
+            return;
+        }
 
-        this._scene = this.closestApp!.app!.scene;
+        // The application is gone if the tree was torn down while we awaited readiness. There is
+        // nothing to configure and nothing the author can act on, so this stays silent.
+        const app = appElement.app;
+        if (!app) {
+            return;
+        }
+
+        this._scene = app.scene;
         this.updateSceneSettings();
 
         this._onReady();
     }
 
     updateSceneSettings() {
-        if (this.scene) {
-            this.scene.fog.type = this._fog;
-            this.scene.fog.color = this._fogColor;
-            this.scene.fog.density = this._fogDensity;
-            this.scene.fog.start = this._fogStart;
-            this.scene.fog.end = this._fogEnd;
-
-            const appElement = this.parentElement as AppElement;
-            appElement.app!.systems.rigidbody!.gravity.copy(this._gravity);
+        if (this._scene) {
+            this._scene.fog.type = this._fog;
+            this._scene.fog.color = this._fogColor;
+            this._scene.fog.density = this._fogDensity;
+            this._scene.fog.start = this._fogStart;
+            this._scene.fog.end = this._fogEnd;
+
+            this._applyGravity(this._gravity);
         }
     }
 
+    /**
+     * Applies gravity to the rigid body system. Resolved through `closestApp` rather than
+     * `parentElement` so that a `<pc-scene>` nested inside a wrapper element behaves the same as
+     * a direct child, matching how `connectedCallback` resolves the application.
+     *
+     * @param value - The gravity to apply.
+     */
+    private _applyGravity(value: Vec3) {
+        this.closestApp?.app?.systems.rigidbody?.gravity.copy(value);
+    }
+
     /**
      * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
      * `none`.
@@ -176,9 +207,8 @@ class SceneElement extends AsyncElement {
      */
     set gravity(value: Vec3) {
         this._gravity = value;
-        if (this.scene) {
-            const appElement = this.parentElement as AppElement;
-            appElement.app!.systems.rigidbody!.gravity.copy(value);
+        if (this._scene) {
+            this._applyGravity(value);
         }
     }