@playcanvas/web-components 0.1.12 → 0.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![License](https://img.shields.io/npm/l/@playcanvas/web-components.svg)](https://github.com/playcanvas/web-components/blob/main/LICENSE)
 [![GitHub Actions Build Status](https://github.com/playcanvas/web-components/actions/workflows/deploy.yml/badge.svg)](https://github.com/playcanvas/web-components/actions/workflows/deploy.yml)
 
-| [User Guide](https://developer.playcanvas.com/user-manual/engine/web-components) | [API Reference](https://api.playcanvas.com/modules/EngineWebComponents.html) | [Examples](https://playcanvas.github.io/web-components/examples) | [Forum](https://forum.playcanvas.com/) | [Discord](https://discord.gg/RSaMRzg) |
+| [User Guide](https://developer.playcanvas.com/user-manual/engine/web-components) | [API Reference](https://api.playcanvas.com/modules/EngineWebComponents.html) | [Examples](https://playcanvas.github.io/web-components/examples) | [Blog](https://blog.playcanvas.com/) | [Forum](https://forum.playcanvas.com/) | [Discord](https://discord.gg/RSaMRzg) |
 
 PlayCanvas Web Components are a set of custom HTML elements for building 3D interactive web apps. Using the declarative nature of HTML makes it both easy and fun to incorporate 3D into your website. Check out this simple example:
 

package/dist/asset.d.ts

@@ -6,7 +6,7 @@ import { Asset } from 'playcanvas';
  * {@link HTMLElement} interface.
  */
 declare class AssetElement extends HTMLElement {
-    private _preload;
+    private _lazy;
     /**
      * The asset that is loaded.
      */
@@ -15,15 +15,15 @@ declare class AssetElement extends HTMLElement {
     createAsset(): void;
     destroyAsset(): void;
     /**
-     * Sets the preload flag of the asset.
-     * @param value - The preload flag.
+     * Sets whether the asset should be loaded lazily.
+     * @param value - The lazy loading flag.
      */
-    set preload(value: boolean);
+    set lazy(value: boolean);
     /**
-     * Gets the preload flag of the asset.
-     * @returns The preload flag.
+     * Gets whether the asset should be loaded lazily.
+     * @returns The lazy loading flag.
      */
-    get preload(): boolean;
+    get lazy(): boolean;
     static get(id: string): Asset | null | undefined;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, _newValue: string): void;

package/dist/components/camera-component.d.ts

@@ -50,7 +50,15 @@ declare class CameraComponentElement extends ComponentElement {
         toneMapping: number | undefined;
     };
     get xrAvailable(): boolean | null | undefined;
+    /**
+     * Starts the camera in XR mode.
+     * @param type - The type of XR mode to start.
+     * @param space - The space to start the camera in.
+     */
     startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'): void;
+    /**
+     * Ends the camera's XR mode.
+     */
     endXr(): void;
     /**
      * Gets the underlying PlayCanvas camera component.

package/dist/components/script-component.d.ts

@@ -29,6 +29,36 @@ declare class ScriptComponentElement extends ComponentElement {
     /** @ignore */
     constructor();
     initComponent(): void;
+    /**
+     * Recursively converts raw attribute data into proper PlayCanvas types. Supported conversions:
+     * - "asset:assetId" → resolves to an Asset instance
+     * - "entity:entityId" → resolves to an Entity instance
+     * - "vec2:1,2" → new Vec2(1,2)
+     * - "vec3:1,2,3" → new Vec3(1,2,3)
+     * - "vec4:1,2,3,4" → new Vec4(1,2,3,4)
+     * - "color:1,0.5,0.5,1" → new Color(1,0.5,0.5,1)
+     * @param item - The item to convert.
+     * @returns The converted item.
+     */
+    private convertAttributes;
+    /**
+     * Preprocess the attributes object by converting its values.
+     * @param attrs - The attributes object to preprocess.
+     * @returns The preprocessed attributes object.
+     */
+    private preprocessAttributes;
+    /**
+     * Recursively merge properties from source into target.
+     * @param target - The target object to merge into.
+     * @param source - The source object to merge from.
+     * @returns The merged object.
+     */
+    private mergeDeep;
+    /**
+     * Update script attributes by merging preprocessed values into the script.
+     * @param script - The script to update.
+     * @param attributes - The attributes to merge into the script.
+     */
     private applyAttributes;
     private handleScriptAttributesChange;
     private handleScriptEnableChange;

package/dist/pwc.cjs

@@ -1003,7 +1003,7 @@ const extToType = new Map([
 class AssetElement extends HTMLElement {
     constructor() {
         super(...arguments);
-        this._preload = false;
+        this._lazy = false;
         /**
          * The asset that is loaded.
          */
@@ -1027,7 +1027,7 @@ class AssetElement extends HTMLElement {
             return;
         }
         this.asset = new playcanvas.Asset(id, type, { url: src });
-        this.asset.preload = this.preload;
+        this.asset.preload = !this._lazy;
     }
     destroyAsset() {
         if (this.asset) {
@@ -1036,32 +1036,32 @@ class AssetElement extends HTMLElement {
         }
     }
     /**
-     * Sets the preload flag of the asset.
-     * @param value - The preload flag.
+     * Sets whether the asset should be loaded lazily.
+     * @param value - The lazy loading flag.
      */
-    set preload(value) {
-        this._preload = value;
+    set lazy(value) {
+        this._lazy = value;
         if (this.asset) {
-            this.asset.preload = value;
+            this.asset.preload = !value;
         }
     }
     /**
-     * Gets the preload flag of the asset.
-     * @returns The preload flag.
+     * Gets whether the asset should be loaded lazily.
+     * @returns The lazy loading flag.
      */
-    get preload() {
-        return this._preload;
+    get lazy() {
+        return this._lazy;
     }
     static get(id) {
         const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
         return assetElement === null || assetElement === undefined ? undefined : assetElement.asset;
     }
     static get observedAttributes() {
-        return ['preload'];
+        return ['lazy'];
     }
     attributeChangedCallback(name, _oldValue, _newValue) {
-        if (name === 'preload') {
-            this.preload = this.hasAttribute('preload');
+        if (name === 'lazy') {
+            this.lazy = this.hasAttribute('lazy');
         }
     }
 }
@@ -1235,6 +1235,11 @@ class CameraComponentElement extends ComponentElement {
         const xrManager = (_a = this.component) === null || _a === undefined ? undefined : _a.system.app.xr;
         return xrManager && xrManager.supported && xrManager.isAvailable(playcanvas.XRTYPE_VR);
     }
+    /**
+     * Starts the camera in XR mode.
+     * @param type - The type of XR mode to start.
+     * @param space - The space to start the camera in.
+     */
     startXr(type, space) {
         if (this.component && this.xrAvailable) {
             this.component.startXr(type, space, {
@@ -1245,6 +1250,9 @@ class CameraComponentElement extends ComponentElement {
             });
         }
     }
+    /**
+     * Ends the camera's XR mode.
+     */
     endXr() {
         if (this.component) {
             this.component.endXr();
@@ -3120,62 +3128,116 @@ class ScriptComponentElement extends ComponentElement {
             }
         });
     }
-    applyAttributes(script, attributes) {
-        try {
-            const attributesObject = attributes ? JSON.parse(attributes) : {};
-            const applyValue = (target, key, value) => {
-                // Handle asset references
-                if (typeof value === 'string' && value.startsWith('asset:')) {
-                    const assetId = value.slice(6);
-                    const assetElement = document.querySelector(`pc-asset#${assetId}`);
-                    if (assetElement) {
-                        target[key] = assetElement.asset;
-                        return;
-                    }
+    /**
+     * Recursively converts raw attribute data into proper PlayCanvas types. Supported conversions:
+     * - "asset:assetId" → resolves to an Asset instance
+     * - "entity:entityId" → resolves to an Entity instance
+     * - "vec2:1,2" → new Vec2(1,2)
+     * - "vec3:1,2,3" → new Vec3(1,2,3)
+     * - "vec4:1,2,3,4" → new Vec4(1,2,3,4)
+     * - "color:1,0.5,0.5,1" → new Color(1,0.5,0.5,1)
+     * @param item - The item to convert.
+     * @returns The converted item.
+     */
+    convertAttributes(item) {
+        if (typeof item === 'string') {
+            if (item.startsWith('asset:')) {
+                const assetId = item.slice(6);
+                const assetElement = document.querySelector(`pc-asset#${assetId}`);
+                if (assetElement) {
+                    return assetElement.asset;
                 }
-                // Handle arrays
-                if (value && typeof value === 'object' && Array.isArray(value)) {
-                    // If it's an array of objects, recursively apply to each object
-                    if (value.length > 0 && typeof value[0] === 'object') {
-                        target[key] = value.map((item) => {
-                            const obj = {};
-                            for (const itemKey in item) {
-                                applyValue(obj, itemKey, item[itemKey]);
-                            }
-                            return obj;
-                        });
-                        return;
-                    }
-                    // Handle vectors
-                    if (value.length === 2 && typeof value[0] === 'number') {
-                        target[key] = new playcanvas.Vec2(value[0], value[1]);
-                        return;
-                    }
-                    if (value.length === 3 && typeof value[0] === 'number') {
-                        target[key] = new playcanvas.Vec3(value[0], value[1], value[2]);
-                        return;
-                    }
-                    if (value.length === 4 && typeof value[0] === 'number') {
-                        target[key] = new playcanvas.Vec4(value[0], value[1], value[2], value[3]);
-                        return;
-                    }
+            }
+            if (item.startsWith('entity:')) {
+                const entityId = item.slice(7);
+                const entityElement = document.querySelector(`pc-entity[name="${entityId}"]`);
+                if (entityElement) {
+                    return entityElement.entity;
                 }
-                // Handle nested objects (non-array)
-                if (value && typeof value === 'object' && !Array.isArray(value)) {
-                    if (!target[key] || typeof target[key] !== 'object') {
-                        target[key] = {};
-                    }
-                    for (const nestedKey in value) {
-                        applyValue(target[key], nestedKey, value[nestedKey]);
-                    }
+            }
+            if (item.startsWith('vec2:')) {
+                const parts = item.slice(5).split(',').map(Number);
+                if (parts.length === 2 && parts.every(v => !isNaN(v))) {
+                    return new playcanvas.Vec2(parts[0], parts[1]);
                 }
-                else {
-                    target[key] = value;
+            }
+            if (item.startsWith('vec3:')) {
+                const parts = item.slice(5).split(',').map(Number);
+                if (parts.length === 3 && parts.every(v => !isNaN(v))) {
+                    return new playcanvas.Vec3(parts[0], parts[1], parts[2]);
+                }
+            }
+            if (item.startsWith('vec4:')) {
+                const parts = item.slice(5).split(',').map(Number);
+                if (parts.length === 4 && parts.every(v => !isNaN(v))) {
+                    return new playcanvas.Vec4(parts[0], parts[1], parts[2], parts[3]);
+                }
+            }
+            if (item.startsWith('color:')) {
+                const parts = item.slice(6).split(',').map(Number);
+                if (parts.length === 4 && parts.every(v => !isNaN(v))) {
+                    return new playcanvas.Color(parts[0], parts[1], parts[2], parts[3]);
                 }
-            };
-            for (const key in attributesObject) {
-                applyValue(script, key, attributesObject[key]);
             }
+            return item;
+        }
+        if (Array.isArray(item)) {
+            // If it's an array of objects, convert each element individually.
+            if (item.length > 0 && typeof item[0] === 'object') {
+                return item.map((el) => this.convertAttributes(el));
+            }
+            // Otherwise, leave the numeric array unchanged but process each element.
+            return item.map((el) => this.convertAttributes(el));
+        }
+        if (item && typeof item === 'object') {
+            const result = {};
+            for (const key in item) {
+                result[key] = this.convertAttributes(item[key]);
+            }
+            return result;
+        }
+        return item;
+    }
+    /**
+     * Preprocess the attributes object by converting its values.
+     * @param attrs - The attributes object to preprocess.
+     * @returns The preprocessed attributes object.
+     */
+    preprocessAttributes(attrs) {
+        return this.convertAttributes(attrs);
+    }
+    /**
+     * Recursively merge properties from source into target.
+     * @param target - The target object to merge into.
+     * @param source - The source object to merge from.
+     * @returns The merged object.
+     */
+    mergeDeep(target, source) {
+        for (const key in source) {
+            if (source[key] &&
+                typeof source[key] === 'object' &&
+                !Array.isArray(source[key])) {
+                if (!target[key] || typeof target[key] !== 'object') {
+                    target[key] = {};
+                }
+                this.mergeDeep(target[key], source[key]);
+            }
+            else {
+                target[key] = source[key];
+            }
+        }
+        return target;
+    }
+    /**
+     * Update script attributes by merging preprocessed values into the script.
+     * @param script - The script to update.
+     * @param attributes - The attributes to merge into the script.
+     */
+    applyAttributes(script, attributes) {
+        try {
+            const attributesObject = attributes ? JSON.parse(attributes) : {};
+            const converted = this.convertAttributes(attributesObject);
+            this.mergeDeep(script, converted);
         }
         catch (error) {
             console.error(`Error parsing attributes JSON string ${attributes}:`, error);
@@ -3204,10 +3266,20 @@ class ScriptComponentElement extends ComponentElement {
     createScript(name, attributes) {
         if (!this.component)
             return null;
-        this.component.on(`create:${name}`, (script) => {
-            this.applyAttributes(script, attributes);
+        let attributesObject = {};
+        if (attributes) {
+            try {
+                attributesObject = JSON.parse(attributes);
+                // Preprocess attributes: convert arrays or strings into vectors, colors, asset references, etc.
+                attributesObject = this.preprocessAttributes(attributesObject);
+            }
+            catch (error) {
+                console.error(`Error parsing attributes JSON string ${attributes}:`, error);
+            }
+        }
+        return this.component.create(name, {
+            properties: attributesObject
         });
-        return this.component.create(name);
     }
     destroyScript(name) {
         if (!this.component)