@playcanvas/web-components 0.9.0 → 0.10.1

package/src/model.ts

@@ -97,10 +97,10 @@ class ModelElement extends AsyncElement {
         return ['asset'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'asset':
-                this.asset = newValue;
+                this.asset = newValue ?? '';
                 break;
         }
     }

package/src/module.ts

@@ -5,6 +5,16 @@ import { basisInitialize, WasmModule } from 'playcanvas';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
  * The ModuleElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * Note that these attributes are read once when the element is created, so changing them later
+ * has no effect.
+ *
+ * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
+ * `Ammo`.
+ * @attribute {string} glue - The URL of the module's glue script.
+ * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+ * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+ * WebAssembly is unavailable.
  */
 class ModuleElement extends HTMLElement {
     private loadPromise: Promise<void>;

package/src/{utils.ts → parse.ts}

@@ -1,22 +1,24 @@
-import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
-
-import { CSS_COLORS } from './colors';
-
 /**
- * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ * Converts HTML attribute values into the values the engine expects. Every element's
+ * `attributeChangedCallback` funnels through this module.
  *
- * - Attribute absent (or removed): the supplied default is used.
- * - Attribute set to the string 'false': `false`.
- * - Attribute present with any other value, including the empty string of a bare boolean
- *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ * The parsers share one contract:
  *
- * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @param defaultValue - The value to use when the attribute is absent or removed.
- * @returns The parsed boolean.
+ * - A `null` value means the attribute is absent or was removed, and yields the supplied default.
+ * - A malformed value yields the same default and logs exactly one `console.warn` naming the
+ *   attribute, so misuse is reported rather than thrown — nothing here throws or rejects.
+ * - A math-type default is cloned on the way out, which is what makes it safe to pass the engine's
+ *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
+ * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
+ *   so they never warn.
+ *
+ * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
+ * literal, and returns `null` instead of falling back to a default.
  */
-export const parseBool = (value: string | null, defaultValue: boolean): boolean => {
-    return value === null ? defaultValue : value !== 'false';
-};
+
+import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+
+import { CSS_COLORS } from './colors';
 
 /**
  * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
@@ -47,6 +49,22 @@ const cloneDefault = <T extends Color | Quat | Vec2 | Vec3 | Vec4 | null>(value:
     return (value === null ? null : value.clone()) as T;
 };
 
+/**
+ * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ *
+ * - Attribute absent (or removed): the supplied default is used.
+ * - Attribute set to the string 'false': `false`.
+ * - Attribute present with any other value, including the empty string of a bare boolean
+ *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed boolean.
+ */
+export const parseBool = (value: string | null, defaultValue: boolean): boolean => {
+    return value === null ? defaultValue : value !== 'false';
+};
+
 /**
  * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
  * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
@@ -89,6 +107,56 @@ export const parseColor = <T extends Color | null>(value: string | null, default
     return cloneDefault(defaultValue);
 };
 
+/**
+ * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+ * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+ * 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 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>,
+    defaultValue: T,
+    attribute: string
+): T => {
+    if (value === null) {
+        return defaultValue;
+    }
+    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
+    if (names.includes(value as T)) {
+        return value as T;
+    }
+    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
+    return defaultValue;
+};
+
+/**
+ * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+ * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+ * finite number — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @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 parsed number.
+ */
+export const parseNumber = <T extends number | null>(value: string | null, defaultValue: T, attribute: string): number | T => {
+    if (value === null) {
+        return defaultValue;
+    }
+    const number = value.trim() === '' ? NaN : Number(value);
+    if (!Number.isFinite(number)) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
+        return defaultValue;
+    }
+    return number;
+};
+
 /**
  * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
  * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
@@ -112,6 +180,27 @@ export const parseQuat = <T extends Quat | null>(value: string | null, defaultVa
     return new Quat().setFromEulerAngles(components[0], components[1], components[2]);
 };
 
+/**
+ * Parse a tags attribute value. The expected format is a comma-separated list of tag names
+ * (e.g. 'enemy, flying'). Surrounding whitespace is trimmed from each name and empty names are
+ * discarded, so a trailing comma or a doubled separator does not produce a blank tag. Returns a
+ * copy of `defaultValue` when the attribute is absent or removed (`null`).
+ *
+ * Every value is valid, so this never warns.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed tag names.
+ */
+export const parseTags = (value: string | null, defaultValue: string[] = []): string[] => {
+    if (value === null) {
+        // Copied for the same reason cloneDefault exists: a parsed result must never alias the
+        // caller's default, or a later mutation would write back through it.
+        return [...defaultValue];
+    }
+    return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+};
+
 /**
  * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
  * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
@@ -178,56 +267,6 @@ export const parseVec4 = <T extends Vec4 | null>(value: string | null, defaultVa
     return new Vec4(components);
 };
 
-/**
- * Resolves an enum attribute value against its set of valid names. Returns the value when it is
- * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
- * 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 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>,
-    defaultValue: T,
-    attribute: string
-): T => {
-    if (value === null) {
-        return defaultValue;
-    }
-    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
-    if (names.includes(value as T)) {
-        return value as T;
-    }
-    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
-    return defaultValue;
-};
-
-/**
- * Parses a number attribute value. Returns the parsed number when the value is a finite number.
- * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
- * finite number — the latter also logs a warning.
- *
- * @param value - The attribute value to parse (`null` when the attribute is absent).
- * @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 parsed number.
- */
-export const parseNumber = <T extends number | null>(value: string | null, defaultValue: T, attribute: string): number | T => {
-    if (value === null) {
-        return defaultValue;
-    }
-    const number = value.trim() === '' ? NaN : Number(value);
-    if (!Number.isFinite(number)) {
-        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
-        return defaultValue;
-    }
-    return number;
-};
-
 /**
  * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
  * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare

package/src/scene.ts

@@ -1,8 +1,7 @@
 import { Color, Scene, Vec3 } from 'playcanvas';
 
-import { AppElement } from './app';
 import { AsyncElement } from './async-element';
-import { parseColor, parseEnum, parseNumber, parseVec3 } from './utils';
+import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
 
 /**
  * The SceneElement interface provides properties and methods for manipulating
@@ -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);
         }
     }
 
@@ -194,7 +224,7 @@ class SceneElement extends AsyncElement {
         return ['fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'fog':
                 this.fog = parseEnum(newValue, ['none', 'linear', 'exp', 'exp2'], 'none', name);

package/src/sky.ts

@@ -3,7 +3,7 @@ import { Asset, EnvLighting, LAYERID_SKYBOX, Quat, Scene, Texture, Vec3 } from '
 import { AppElement } from './app';
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
-import { parseBool, parseEnum, parseNumber, parseVec3 } from './utils';
+import { parseBool, parseEnum, parseNumber, parseVec3 } from './parse';
 
 /**
  * The SkyElement interface provides properties and methods for manipulating
@@ -270,10 +270,10 @@ class SkyElement extends AsyncElement {
         return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'asset':
-                this.asset = newValue;
+                this.asset = newValue ?? '';
                 break;
             case 'center':
                 this.center = parseVec3(newValue, new Vec3(0, 0.01, 0), name);