@playcanvas/web-components 0.8.1 → 0.9.0

package/src/components/button-component.ts

@@ -2,9 +2,9 @@ import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Butt
 
 import { AssetElement } from '../asset';
 import { ComponentElement } from './component';
-import { getEntity, parseColor, parseEnum, parseVec4 } from '../utils';
+import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../utils';
 
-const transitionModes = new Map<string, number>([
+const transitionModes = new Map<'tint' | 'sprite', number>([
     ['tint', BUTTON_TRANSITION_MODE_TINT],
     ['sprite', BUTTON_TRANSITION_MODE_SPRITE_CHANGE]
 ]);
@@ -24,7 +24,7 @@ class ButtonComponentElement extends ComponentElement {
 
     private _hitPadding = new Vec4(0, 0, 0, 0);
 
-    private _transitionMode: number = BUTTON_TRANSITION_MODE_TINT;
+    private _transitionMode: 'tint' | 'sprite' = 'tint';
 
     private _hoverTint = new Color(1, 1, 1, 1);
 
@@ -55,7 +55,7 @@ class ButtonComponentElement extends ComponentElement {
         const data: Record<string, any> = {
             active: this._active,
             hitPadding: this._hitPadding,
-            transitionMode: this._transitionMode,
+            transitionMode: transitionModes.get(this._transitionMode),
             hoverTint: this._hoverTint,
             pressedTint: this._pressedTint,
             inactiveTint: this._inactiveTint,
@@ -94,8 +94,8 @@ class ButtonComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas button component.
      * @returns The button component.
      */
-    get component(): ButtonComponent | null {
-        return super.component as ButtonComponent | null;
+    get component(): ButtonComponent {
+        return super.component as ButtonComponent;
     }
 
     /**
@@ -158,13 +158,14 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets how the button reacts to being hovered/pressed. Can be `tint` (0) or `sprite` (1).
+     * Sets how the button reacts to being hovered/pressed. Can be `tint` or `sprite`. Defaults to
+     * `tint`.
      * @param value - The transition mode.
      */
-    set transitionMode(value: number) {
+    set transitionMode(value: 'tint' | 'sprite') {
         this._transitionMode = value;
         if (this.component) {
-            this.component.transitionMode = value;
+            this.component.transitionMode = transitionModes.get(value) ?? BUTTON_TRANSITION_MODE_TINT;
         }
     }
 
@@ -400,46 +401,46 @@ class ButtonComponentElement extends ComponentElement {
 
         switch (name) {
             case 'active':
-                this.active = newValue !== 'false';
+                this.active = parseBool(newValue, true);
                 break;
             case 'image':
                 this.image = newValue;
                 break;
             case 'hit-padding':
-                this.hitPadding = parseVec4(newValue);
+                this.hitPadding = parseVec4(newValue, Vec4.ZERO, name);
                 break;
             case 'transition-mode':
-                this.transitionMode = parseEnum(newValue, transitionModes, BUTTON_TRANSITION_MODE_TINT);
+                this.transitionMode = parseEnum(newValue, transitionModes, 'tint', name);
                 break;
             case 'hover-tint':
-                this.hoverTint = parseColor(newValue);
+                this.hoverTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'pressed-tint':
-                this.pressedTint = parseColor(newValue);
+                this.pressedTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'inactive-tint':
-                this.inactiveTint = parseColor(newValue);
+                this.inactiveTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'fade-duration':
-                this.fadeDuration = Number(newValue);
+                this.fadeDuration = parseNumber(newValue, 0, name);
                 break;
             case 'hover-sprite-asset':
                 this.hoverSpriteAsset = newValue;
                 break;
             case 'hover-sprite-frame':
-                this.hoverSpriteFrame = Number(newValue);
+                this.hoverSpriteFrame = parseNumber(newValue, 0, name);
                 break;
             case 'pressed-sprite-asset':
                 this.pressedSpriteAsset = newValue;
                 break;
             case 'pressed-sprite-frame':
-                this.pressedSpriteFrame = Number(newValue);
+                this.pressedSpriteFrame = parseNumber(newValue, 0, name);
                 break;
             case 'inactive-sprite-asset':
                 this.inactiveSpriteAsset = newValue;
                 break;
             case 'inactive-sprite-frame':
-                this.inactiveSpriteFrame = Number(newValue);
+                this.inactiveSpriteFrame = parseNumber(newValue, 0, name);
                 break;
         }
     }
@@ -447,4 +448,10 @@ class ButtonComponentElement extends ComponentElement {
 
 customElements.define('pc-button', ButtonComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-button': ButtonComponentElement;
+    }
+}
+
 export { ButtonComponentElement };

package/src/components/camera-component.ts

@@ -1,9 +1,9 @@
 import { CameraComponent, Color, Vec4, GAMMA_NONE, GAMMA_SRGB, PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_NEUTRAL, TONEMAP_ACES2, TONEMAP_ACES, TONEMAP_HEJL, TONEMAP_NONE, XRTYPE_VR } from 'playcanvas';
 
 import { ComponentElement } from './component';
-import { parseColor, parseVec4 } from '../utils';
+import { parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../utils';
 
-const tonemaps = new Map([
+const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral', number>([
     ['none', TONEMAP_NONE],
     ['linear', TONEMAP_LINEAR],
     ['filmic', TONEMAP_FILMIC],
@@ -77,7 +77,7 @@ class CameraComponentElement extends ComponentElement {
             gammaCorrection: this._gamma === 'srgb' ? GAMMA_SRGB : GAMMA_NONE,
             horizontalFov: this._horizontalFov,
             nearClip: this._nearClip,
-            orthographic: this._orthographic,
+            projection: this._orthographic ? PROJECTION_ORTHOGRAPHIC : PROJECTION_PERSPECTIVE,
             orthoHeight: this._orthoHeight,
             priority: this._priority,
             rect: this._rect,
@@ -119,8 +119,8 @@ class CameraComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas camera component.
      * @returns The camera component.
      */
-    get component(): CameraComponent | null {
-        return super.component as CameraComponent | null;
+    get component(): CameraComponent {
+        return super.component as CameraComponent;
     }
 
     /**
@@ -495,58 +495,58 @@ class CameraComponentElement extends ComponentElement {
 
         switch (name) {
             case 'clear-color':
-                this.clearColor = parseColor(newValue);
+                this.clearColor = parseColor(newValue, new Color(0.75, 0.75, 0.75, 1), name);
                 break;
             case 'clear-color-buffer':
-                this.clearColorBuffer = newValue !== 'false';
+                this.clearColorBuffer = parseBool(newValue, true);
                 break;
             case 'clear-depth-buffer':
-                this.clearDepthBuffer = newValue !== 'false';
+                this.clearDepthBuffer = parseBool(newValue, true);
                 break;
             case 'clear-stencil-buffer':
-                this.clearStencilBuffer = newValue !== 'false';
+                this.clearStencilBuffer = parseBool(newValue, false);
                 break;
             case 'cull-faces':
-                this.cullFaces = newValue !== 'false';
+                this.cullFaces = parseBool(newValue, true);
                 break;
             case 'far-clip':
-                this.farClip = parseFloat(newValue);
+                this.farClip = parseNumber(newValue, 1000, name);
                 break;
             case 'flip-faces':
-                this.flipFaces = newValue !== 'true';
+                this.flipFaces = parseBool(newValue, false);
                 break;
             case 'fov':
-                this.fov = parseFloat(newValue);
+                this.fov = parseNumber(newValue, 45, name);
                 break;
             case 'frustum-culling':
-                this.frustumCulling = newValue !== 'false';
+                this.frustumCulling = parseBool(newValue, true);
                 break;
             case 'gamma':
-                this.gamma = newValue as 'linear' | 'srgb';
+                this.gamma = parseEnum(newValue, ['linear', 'srgb'], 'srgb', name);
                 break;
             case 'horizontal-fov':
-                this.horizontalFov = this.hasAttribute('horizontal-fov');
+                this.horizontalFov = parseBool(newValue, false);
                 break;
             case 'near-clip':
-                this.nearClip = parseFloat(newValue);
+                this.nearClip = parseNumber(newValue, 0.1, name);
                 break;
             case 'orthographic':
-                this.orthographic = this.hasAttribute('orthographic');
+                this.orthographic = parseBool(newValue, false);
                 break;
             case 'ortho-height':
-                this.orthoHeight = parseFloat(newValue);
+                this.orthoHeight = parseNumber(newValue, 10, name);
                 break;
             case 'priority':
-                this.priority = parseFloat(newValue);
+                this.priority = parseNumber(newValue, 0, name);
                 break;
             case 'rect':
-                this.rect = parseVec4(newValue);
+                this.rect = parseVec4(newValue, new Vec4(0, 0, 1, 1), name);
                 break;
             case 'scissor-rect':
-                this.scissorRect = parseVec4(newValue);
+                this.scissorRect = parseVec4(newValue, new Vec4(0, 0, 1, 1), name);
                 break;
             case 'tonemap':
-                this.tonemap = newValue as 'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral';
+                this.tonemap = parseEnum(newValue, tonemaps, 'none', name);
                 break;
         }
     }
@@ -554,4 +554,10 @@ class CameraComponentElement extends ComponentElement {
 
 customElements.define('pc-camera', CameraComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-camera': CameraComponentElement;
+    }
+}
+
 export { CameraComponentElement };

package/src/components/collision-component.ts

@@ -1,7 +1,7 @@
 import { CollisionComponent, Quat, Vec3 } from 'playcanvas';
 
 import { ComponentElement } from './component';
-import { parseQuat, parseVec3 } from '../utils';
+import { parseBool, parseEnum, parseNumber, parseQuat, parseVec3 } from '../utils';
 
 /**
  * The CollisionComponentElement interface provides properties and methods for manipulating
@@ -26,7 +26,7 @@ class CollisionComponentElement extends ComponentElement {
 
     private _radius: number = 0.5;
 
-    private _type: string = 'box';
+    private _type: 'box' | 'capsule' | 'compound' | 'cone' | 'cylinder' | 'mesh' | 'sphere' = 'box';
 
     /** @ignore */
     constructor() {
@@ -50,8 +50,8 @@ class CollisionComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas collision component.
      * @returns The collision component.
      */
-    get component(): CollisionComponent | null {
-        return super.component as CollisionComponent | null;
+    get component(): CollisionComponent {
+        return super.component as CollisionComponent;
     }
 
     set angularOffset(value: Quat) {
@@ -131,7 +131,7 @@ class CollisionComponentElement extends ComponentElement {
         return this._radius;
     }
 
-    set type(value: string) {
+    set type(value: 'box' | 'capsule' | 'compound' | 'cone' | 'cylinder' | 'mesh' | 'sphere') {
         this._type = value;
         if (this.component) {
             this.component.type = value;
@@ -151,28 +151,28 @@ class CollisionComponentElement extends ComponentElement {
 
         switch (name) {
             case 'angular-offset':
-                this.angularOffset = parseQuat(newValue);
+                this.angularOffset = parseQuat(newValue, Quat.IDENTITY, name);
                 break;
             case 'axis':
-                this.axis = parseInt(newValue, 10);
+                this.axis = parseNumber(newValue, 1, name);
                 break;
             case 'convex-hull':
-                this.convexHull = this.hasAttribute('convex-hull');
+                this.convexHull = parseBool(newValue, false);
                 break;
             case 'half-extents':
-                this.halfExtents = parseVec3(newValue);
+                this.halfExtents = parseVec3(newValue, new Vec3(0.5, 0.5, 0.5), name);
                 break;
             case 'height':
-                this.height = parseFloat(newValue);
+                this.height = parseNumber(newValue, 2, name);
                 break;
             case 'linear-offset':
-                this.linearOffset = parseVec3(newValue);
+                this.linearOffset = parseVec3(newValue, Vec3.ZERO, name);
                 break;
             case 'radius':
-                this.radius = parseFloat(newValue);
+                this.radius = parseNumber(newValue, 0.5, name);
                 break;
             case 'type':
-                this.type = newValue;
+                this.type = parseEnum(newValue, ['box', 'capsule', 'compound', 'cone', 'cylinder', 'mesh', 'sphere'], 'box', name);
                 break;
         }
     }
@@ -180,4 +180,10 @@ class CollisionComponentElement extends ComponentElement {
 
 customElements.define('pc-collision', CollisionComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-collision': CollisionComponentElement;
+    }
+}
+
 export { CollisionComponentElement };

package/src/components/component.ts

@@ -1,6 +1,8 @@
 import { Component } from 'playcanvas';
 
+import { AppElement } from '../app';
 import { AsyncElement } from '../async-element';
+import { parseBool } from '../utils';
 
 /**
  * Represents a component in the PlayCanvas engine.
@@ -14,6 +16,8 @@ class ComponentElement extends AsyncElement {
 
     private _component: Component | null = null;
 
+    private _appElement: AppElement | null = null;
+
     /**
      * Creates a new ComponentElement instance.
      *
@@ -33,33 +37,48 @@ class ComponentElement extends AsyncElement {
 
     async addComponent() {
         const entityElement = this.closestEntity;
-        if (entityElement) {
-            await entityElement.ready();
-            // Add the component to the entity
-            const data = this.getInitialComponentData();
-            this._component = entityElement.entity!.addComponent(this._componentName, data);
+        if (!entityElement) {
+            // A component can only exist on an entity, so an element placed outside one is inert.
+            // It still becomes ready (with a null `component`), so warn rather than fail silently
+            const label = this.id ? ` '${this.id}'` : '';
+            console.warn(`${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`);
+            return;
         }
+
+        await entityElement.ready();
+        // Add the component to the entity
+        const data = this.getInitialComponentData();
+        this._component = entityElement.entity!.addComponent(this._componentName, data);
     }
 
     initComponent() {}
 
     async connectedCallback() {
-        await this.closestApp?.ready();
+        this._appElement = this.closestApp ?? null;
+        await this._appElement?.ready();
         await this.addComponent();
         this.initComponent();
         this._onReady();
     }
 
     disconnectedCallback() {
-        // Remove the component when the element is disconnected
-        if (this.component && this.component.entity) {
-            this._component!.entity.removeComponent(this._componentName);
-            this._component = null;
+        // Remove the component when the element is disconnected. Skip this when the owning
+        // application has already been destroyed — removing a <pc-app> disconnects it before
+        // its children, taking the component systems with it.
+        if (this._appElement?.app && this._component?.entity) {
+            this._component.entity.removeComponent(this._componentName);
         }
+        this._component = null;
+        this._appElement = null;
     }
 
-    get component(): Component | null {
-        return this._component;
+    /**
+     * The PlayCanvas component instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The component instance.
+     */
+    get component(): Component {
+        return this._component!;
     }
 
     /**
@@ -88,7 +107,7 @@ class ComponentElement extends AsyncElement {
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         switch (name) {
             case 'enabled':
-                this.enabled = newValue !== 'false';
+                this.enabled = parseBool(newValue, true);
                 break;
         }
     }

package/src/components/element-component.ts

@@ -2,7 +2,7 @@ import { Color, ElementComponent, Vec2, Vec4 } from 'playcanvas';
 
 import { AssetElement } from '../asset';
 import { ComponentElement } from './component';
-import { parseColor, parseVec2, parseVec4 } from '../utils';
+import { parseBool, parseColor, parseEnum, parseNumber, parseVec2, parseVec4 } from '../utils';
 
 /**
  * The ElementComponentElement interface provides properties and methods for manipulating
@@ -15,8 +15,6 @@ import { parseColor, parseVec2, parseVec4 } from '../utils';
 class ElementComponentElement extends ComponentElement {
     private _anchor: Vec4 = new Vec4(0.5, 0.5, 0.5, 0.5);
 
-    private _asset: string = '';
-
     private _autoWidth: boolean = true;
 
     private _autoHeight: boolean = true;
@@ -29,6 +27,8 @@ class ElementComponentElement extends ComponentElement {
 
     private _enableMarkup: boolean = false;
 
+    private _fontAsset: string = '';
+
     private _fontSize: number = 32;
 
     private _maxFontSize: number = 32;
@@ -116,7 +116,7 @@ class ElementComponentElement extends ComponentElement {
 
         // Asset references are resolved from `<pc-asset>` element ids to engine asset ids. They are
         // only included when they resolve, so image/group elements (with no font) don't error.
-        const fontAsset = AssetElement.get(this._asset);
+        const fontAsset = AssetElement.get(this._fontAsset);
         if (fontAsset) {
             data.fontAsset = fontAsset.id;
         }
@@ -148,8 +148,8 @@ class ElementComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas element component.
      * @returns The element component.
      */
-    get component(): ElementComponent | null {
-        return super.component as ElementComponent | null;
+    get component(): ElementComponent {
+        return super.component as ElementComponent;
     }
 
     /**
@@ -171,26 +171,6 @@ class ElementComponentElement extends ComponentElement {
         return this._anchor;
     }
 
-    /**
-     * Sets the id of the `pc-asset` to use for the font (text elements).
-     * @param value - The asset ID.
-     */
-    set asset(value: string) {
-        this._asset = value;
-        const asset = AssetElement.get(value);
-        if (this.component && asset) {
-            this.component.fontAsset = asset.id;
-        }
-    }
-
-    /**
-     * Gets the id of the `pc-asset` to use for the font.
-     * @returns The asset ID.
-     */
-    get asset() {
-        return this._asset;
-    }
-
     /**
      * Sets whether the element component should automatically adjust its width to the text content
      * (text elements only).
@@ -269,6 +249,26 @@ class ElementComponentElement extends ComponentElement {
         return this._enableMarkup;
     }
 
+    /**
+     * Sets the id of the `pc-asset` to use for the font (text elements).
+     * @param value - The font asset ID.
+     */
+    set fontAsset(value: string) {
+        this._fontAsset = value;
+        const asset = AssetElement.get(value);
+        if (this.component && asset) {
+            this.component.fontAsset = asset.id;
+        }
+    }
+
+    /**
+     * Gets the id of the `pc-asset` to use for the font.
+     * @returns The font asset ID.
+     */
+    get fontAsset() {
+        return this._fontAsset;
+    }
+
     /**
      * Sets the font size of the element component.
      * @param value - The font size.
@@ -658,13 +658,13 @@ class ElementComponentElement extends ComponentElement {
         return [
             ...super.observedAttributes,
             'anchor',
-            'asset',
             'auto-width',
             'auto-height',
             'auto-fit-width',
             'auto-fit-height',
             'color',
             'enable-markup',
+            'font-asset',
             'font-size',
             'max-font-size',
             'min-font-size',
@@ -691,64 +691,64 @@ class ElementComponentElement extends ComponentElement {
 
         switch (name) {
             case 'anchor':
-                this.anchor = parseVec4(newValue);
-                break;
-            case 'asset':
-                this.asset = newValue;
+                this.anchor = parseVec4(newValue, new Vec4(0.5, 0.5, 0.5, 0.5), name);
                 break;
             case 'auto-width':
-                this.autoWidth = newValue !== 'false';
+                this.autoWidth = parseBool(newValue, true);
                 break;
             case 'auto-height':
-                this.autoHeight = newValue !== 'false';
+                this.autoHeight = parseBool(newValue, true);
                 break;
             case 'auto-fit-width':
-                this.autoFitWidth = newValue !== 'false';
+                this.autoFitWidth = parseBool(newValue, false);
                 break;
             case 'auto-fit-height':
-                this.autoFitHeight = newValue !== 'false';
+                this.autoFitHeight = parseBool(newValue, false);
                 break;
             case 'color':
-                this.color = parseColor(newValue);
+                this.color = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'enable-markup':
-                this.enableMarkup = this.hasAttribute(name);
+                this.enableMarkup = parseBool(newValue, false);
+                break;
+            case 'font-asset':
+                this.fontAsset = newValue;
                 break;
             case 'font-size':
-                this.fontSize = Number(newValue);
+                this.fontSize = parseNumber(newValue, 32, name);
                 break;
             case 'max-font-size':
-                this.maxFontSize = Number(newValue);
+                this.maxFontSize = parseNumber(newValue, 32, name);
                 break;
             case 'min-font-size':
-                this.minFontSize = Number(newValue);
+                this.minFontSize = parseNumber(newValue, 8, name);
                 break;
             case 'height':
-                this.height = Number(newValue);
+                this.height = parseNumber(newValue, 0, name);
                 break;
             case 'line-height':
-                this.lineHeight = Number(newValue);
+                this.lineHeight = parseNumber(newValue, 32, name);
                 break;
             case 'margin':
-                this.margin = parseVec4(newValue);
+                this.margin = parseVec4(newValue, null, name);
                 break;
             case 'mask':
-                this.mask = this.hasAttribute(name);
+                this.mask = parseBool(newValue, false);
                 break;
             case 'opacity':
-                this.opacity = Number(newValue);
+                this.opacity = parseNumber(newValue, 1, name);
                 break;
             case 'pivot':
-                this.pivot = parseVec2(newValue);
+                this.pivot = parseVec2(newValue, new Vec2(0.5, 0.5), name);
                 break;
             case 'pixels-per-unit':
-                this.pixelsPerUnit = Number(newValue);
+                this.pixelsPerUnit = parseNumber(newValue, null, name);
                 break;
             case 'sprite-asset':
                 this.spriteAsset = newValue;
                 break;
             case 'sprite-frame':
-                this.spriteFrame = Number(newValue);
+                this.spriteFrame = parseNumber(newValue, 0, name);
                 break;
             case 'text':
                 this.text = newValue;
@@ -757,16 +757,16 @@ class ElementComponentElement extends ComponentElement {
                 this.textureAsset = newValue;
                 break;
             case 'type':
-                this.type = newValue as 'group' | 'image' | 'text';
+                this.type = parseEnum(newValue, ['group', 'image', 'text'], 'group', name);
                 break;
             case 'use-input':
-                this.useInput = this.hasAttribute(name);
+                this.useInput = parseBool(newValue, false);
                 break;
             case 'width':
-                this.width = Number(newValue);
+                this.width = parseNumber(newValue, 0, name);
                 break;
             case 'wrap-lines':
-                this.wrapLines = this.hasAttribute(name);
+                this.wrapLines = parseBool(newValue, false);
                 break;
         }
     }
@@ -774,4 +774,10 @@ class ElementComponentElement extends ComponentElement {
 
 customElements.define('pc-element', ElementComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-element': ElementComponentElement;
+    }
+}
+
 export { ElementComponentElement };