@playcanvas/web-components 0.8.1 → 0.9.0

package/src/components/script.ts

@@ -1,23 +1,64 @@
+import { Script } from 'playcanvas';
+
+import { AsyncElement } from '../async-element';
+import { parseBool } from '../utils';
+
 /**
  * The ScriptElement interface provides properties and methods for manipulating
  * `<pc-script>` elements. The ScriptElement interface also inherits the properties and
- * methods of the {@link HTMLElement} interface.
+ * methods of the {@link AsyncElement} interface.
+ *
+ * Script attributes can be supplied through two channels:
+ *
+ * - **Per-property attributes**: any non-reserved attribute on the element maps to the script
+ *   attribute of the same name (kebab-case to camelCase, e.g. `focus-point` → `focusPoint`).
+ *   Values are parsed according to the type of the attribute's current value — initially the
+ *   script's declared default (numbers, booleans, strings, Vec2/3/4, Color, Quat as Euler
+ *   angles) — and the `asset:`/`entity:`/`vec2:`/`vec3:`/`vec4:`/`color:` prefixes may be used
+ *   to be explicit.
+ * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
+ *   names that collide with reserved HTML attribute names (e.g. `title`).
+ *
+ * When both specify the same attribute, the per-property attribute wins — at creation and
+ * whenever either channel changes at runtime. The element's own `name` and `enabled`
+ * attributes configure the element itself and are not script attributes.
+ *
+ * Changing `name` on a live element destroys the old-name script instance and creates the
+ * new-name one, re-applying both attribute channels to it.
+ *
+ * The element becomes ready once its script instance has been created by the parent
+ * `<pc-scripts>` element.
  */
-class ScriptElement extends HTMLElement {
-    private _attributes: string = '{}';
+class ScriptElement extends AsyncElement {
+    private _attributes: Record<string, any> = {};
 
     private _enabled: boolean = true;
 
-    private _name: string = '';
+    /**
+     * Whether readiness has been signalled. Creation can happen more than once over an
+     * element's life (a runtime `name` change recreates the instance), but `ready` is a
+     * one-shot signal, so only the first successful creation fires it.
+     */
+    private _readySignalled: boolean = false;
 
     /**
-     * Sets the attributes of the script.
+     * The Script instance created for this element by its parent `<pc-scripts>` element.
+     * @ignore
+     */
+    _script: Script | null = null;
+
+    /**
+     * Sets the attributes of the script as an object. Values are converted with the same rules
+     * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
+     * `color:` prefixed strings are resolved, and a plain numeric array is converted to the
+     * type of the attribute it targets when that attribute currently holds a Vec2, Vec3, Vec4
+     * or Color.
      * @param value - The attributes of the script.
      */
-    set scriptAttributes(value: string) {
-        this._attributes = value;
+    set scriptAttributes(value: Record<string, any>) {
+        this._attributes = value ?? {};
         this.dispatchEvent(new CustomEvent('scriptattributeschange', {
-            detail: { attributes: value },
+            detail: { attributes: this._attributes },
             bubbles: true
         }));
     }
@@ -26,7 +67,7 @@ class ScriptElement extends HTMLElement {
      * Gets the attributes of the script.
      * @returns The attributes of the script.
      */
-    get scriptAttributes() {
+    get scriptAttributes(): Record<string, any> {
         return this._attributes;
     }
 
@@ -51,11 +92,20 @@ class ScriptElement extends HTMLElement {
     }
 
     /**
-     * Sets the name of the script to create.
+     * Sets the name of the script to create. The `name` attribute is the single source of truth
+     * (it is what the parent `<pc-scripts>` element reads when creating the instance), so the
+     * property writes through to it — assigning before insertion works as expected:
+     *
+     * ```js
+     * const script = document.createElement('pc-script');
+     * script.name = 'rotate';
+     * scriptsElement.appendChild(script);
+     * await script.ready();
+     * ```
      * @param value - The name.
      */
     set name(value: string) {
-        this._name = value;
+        this.setAttribute('name', value);
     }
 
     /**
@@ -63,23 +113,67 @@ class ScriptElement extends HTMLElement {
      * @returns The name.
      */
     get name() {
-        return this._name;
+        return this.getAttribute('name') ?? '';
+    }
+
+    /**
+     * Gets the {@link Script} instance created for this element. Returns `null` until the
+     * instance exists — await {@link whenReady} or the element's `ready()` promise before
+     * accessing it.
+     * @returns The script instance, or `null`.
+     */
+    get script(): Script | null {
+        return this._script;
+    }
+
+    connectedCallback() {
+        // Script instances are created by the parent pc-scripts element, so an element placed
+        // anywhere else is inert and never becomes ready - warn rather than hang silently
+        if (this.parentElement?.tagName !== 'PC-SCRIPTS') {
+            console.warn(`pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`);
+        }
+    }
+
+    /**
+     * Called by the parent `<pc-scripts>` element when the script instance has been created.
+     * @ignore
+     */
+    _onScriptCreated() {
+        if (this._readySignalled) return;
+        this._readySignalled = true;
+        this._onReady();
     }
 
     static get observedAttributes() {
         return ['attributes', 'enabled', 'name'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, oldValue: string, newValue: string) {
         switch (name) {
             case 'attributes':
-                this.scriptAttributes = newValue;
+                if (newValue === null) {
+                    this.scriptAttributes = {};
+                    break;
+                }
+                try {
+                    this.scriptAttributes = JSON.parse(newValue);
+                } catch (error) {
+                    console.warn(`Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`);
+                }
                 break;
             case 'enabled':
-                this.enabled = newValue !== 'false';
+                this.enabled = parseBool(newValue, true);
                 break;
             case 'name':
-                this.name = newValue;
+                // The first set is handled by the parent's creation paths (the boot query and
+                // the added-node mutation), so only a genuine rename is signalled here. Note
+                // that setAttribute fires this callback even when the value is unchanged.
+                if (oldValue !== null && oldValue !== newValue) {
+                    this.dispatchEvent(new CustomEvent('scriptnamechange', {
+                        detail: { oldName: oldValue, newName: newValue },
+                        bubbles: true
+                    }));
+                }
                 break;
         }
     }
@@ -87,4 +181,10 @@ class ScriptElement extends HTMLElement {
 
 customElements.define('pc-script', ScriptElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-script': ScriptElement;
+    }
+}
+
 export { ScriptElement };

package/src/components/scrollbar-component.ts

@@ -1,9 +1,9 @@
 import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL, ScrollbarComponent } from 'playcanvas';
 
 import { ComponentElement } from './component';
-import { getEntity, parseEnum } from '../utils';
+import { getEntity, parseEnum, parseNumber } from '../utils';
 
-const orientations = new Map<string, number>([
+const orientations = new Map<'horizontal' | 'vertical', number>([
     ['horizontal', ORIENTATION_HORIZONTAL],
     ['vertical', ORIENTATION_VERTICAL]
 ]);
@@ -17,7 +17,7 @@ const orientations = new Map<string, number>([
  * @category Components
  */
 class ScrollbarComponentElement extends ComponentElement {
-    private _orientation: number = ORIENTATION_HORIZONTAL;
+    private _orientation: 'horizontal' | 'vertical' = 'horizontal';
 
     private _value = 0;
 
@@ -32,7 +32,7 @@ class ScrollbarComponentElement extends ComponentElement {
 
     getInitialComponentData() {
         const data: Record<string, any> = {
-            orientation: this._orientation,
+            orientation: orientations.get(this._orientation),
             value: this._value,
             handleSize: this._handleSize
         };
@@ -49,18 +49,19 @@ class ScrollbarComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas scrollbar component.
      * @returns The scrollbar component.
      */
-    get component(): ScrollbarComponent | null {
-        return super.component as ScrollbarComponent | null;
+    get component(): ScrollbarComponent {
+        return super.component as ScrollbarComponent;
     }
 
     /**
-     * Sets the orientation of the scrollbar. Can be `horizontal` (0) or `vertical` (1).
+     * Sets the orientation of the scrollbar. Can be `horizontal` or `vertical`. Defaults to
+     * `horizontal`.
      * @param value - The orientation.
      */
-    set orientation(value: number) {
+    set orientation(value: 'horizontal' | 'vertical') {
         this._orientation = value;
         if (this.component) {
-            this.component.orientation = value;
+            this.component.orientation = orientations.get(value) ?? ORIENTATION_HORIZONTAL;
         }
     }
 
@@ -146,13 +147,13 @@ class ScrollbarComponentElement extends ComponentElement {
 
         switch (name) {
             case 'orientation':
-                this.orientation = parseEnum(newValue, orientations, ORIENTATION_HORIZONTAL);
+                this.orientation = parseEnum(newValue, orientations, 'horizontal', name);
                 break;
             case 'value':
-                this.value = Number(newValue);
+                this.value = parseNumber(newValue, 0, name);
                 break;
             case 'handle-size':
-                this.handleSize = Number(newValue);
+                this.handleSize = parseNumber(newValue, 0.5, name);
                 break;
             case 'handle':
                 this.handle = newValue;
@@ -163,4 +164,10 @@ class ScrollbarComponentElement extends ComponentElement {
 
 customElements.define('pc-scrollbar', ScrollbarComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scrollbar': ScrollbarComponentElement;
+    }
+}
+
 export { ScrollbarComponentElement };

package/src/components/scrollview-component.ts

@@ -1,15 +1,15 @@
 import { SCROLL_MODE_BOUNCE, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, ScrollViewComponent, Vec2 } from 'playcanvas';
 
 import { ComponentElement } from './component';
-import { getEntity, parseEnum, parseVec2 } from '../utils';
+import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../utils';
 
-const scrollModes = new Map<string, number>([
+const scrollModes = new Map<'clamp' | 'bounce' | 'infinite', number>([
     ['clamp', SCROLL_MODE_CLAMP],
     ['bounce', SCROLL_MODE_BOUNCE],
     ['infinite', SCROLL_MODE_INFINITE]
 ]);
 
-const visibilities = new Map<string, number>([
+const visibilities = new Map<'always' | 'when-required', number>([
     ['always', SCROLLBAR_VISIBILITY_SHOW_ALWAYS],
     ['when-required', SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED]
 ]);
@@ -27,7 +27,7 @@ class ScrollViewComponentElement extends ComponentElement {
 
     private _vertical = true;
 
-    private _scrollMode: number = SCROLL_MODE_BOUNCE;
+    private _scrollMode: 'clamp' | 'bounce' | 'infinite' = 'bounce';
 
     private _bounceAmount = 0.1;
 
@@ -37,9 +37,9 @@ class ScrollViewComponentElement extends ComponentElement {
 
     private _mouseWheelSensitivity = new Vec2(1, 1);
 
-    private _horizontalScrollbarVisibility: number = SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+    private _horizontalScrollbarVisibility: 'always' | 'when-required' = 'when-required';
 
-    private _verticalScrollbarVisibility: number = SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+    private _verticalScrollbarVisibility: 'always' | 'when-required' = 'when-required';
 
     private _viewport = '';
 
@@ -58,13 +58,13 @@ class ScrollViewComponentElement extends ComponentElement {
         const data: Record<string, any> = {
             horizontal: this._horizontal,
             vertical: this._vertical,
-            scrollMode: this._scrollMode,
+            scrollMode: scrollModes.get(this._scrollMode),
             bounceAmount: this._bounceAmount,
             friction: this._friction,
             useMouseWheel: this._useMouseWheel,
             mouseWheelSensitivity: this._mouseWheelSensitivity,
-            horizontalScrollbarVisibility: this._horizontalScrollbarVisibility,
-            verticalScrollbarVisibility: this._verticalScrollbarVisibility
+            horizontalScrollbarVisibility: visibilities.get(this._horizontalScrollbarVisibility),
+            verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
         };
 
         const viewport = getEntity(this._viewport);
@@ -94,8 +94,8 @@ class ScrollViewComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas scroll view component.
      * @returns The scroll view component.
      */
-    get component(): ScrollViewComponent | null {
-        return super.component as ScrollViewComponent | null;
+    get component(): ScrollViewComponent {
+        return super.component as ScrollViewComponent;
     }
 
     /**
@@ -138,13 +138,13 @@ class ScrollViewComponentElement extends ComponentElement {
 
     /**
      * Sets how the scroll view should behave when the content is scrolled beyond its bounds. Can be
-     * `clamp` (0), `bounce` (1) or `infinite` (2).
+     * `clamp`, `bounce` or `infinite`. Defaults to `bounce`.
      * @param value - The scroll mode.
      */
-    set scrollMode(value: number) {
+    set scrollMode(value: 'clamp' | 'bounce' | 'infinite') {
         this._scrollMode = value;
         if (this.component) {
-            this.component.scrollMode = value;
+            this.component.scrollMode = scrollModes.get(value) ?? SCROLL_MODE_BOUNCE;
         }
     }
 
@@ -235,13 +235,14 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the visibility of the horizontal scrollbar. Can be `always` (0) or `when-required` (1).
+     * Sets the visibility of the horizontal scrollbar. Can be `always` or `when-required`.
+     * Defaults to `when-required`.
      * @param value - The horizontal scrollbar visibility.
      */
-    set horizontalScrollbarVisibility(value: number) {
+    set horizontalScrollbarVisibility(value: 'always' | 'when-required') {
         this._horizontalScrollbarVisibility = value;
         if (this.component) {
-            this.component.horizontalScrollbarVisibility = value;
+            this.component.horizontalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -254,13 +255,14 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the visibility of the vertical scrollbar. Can be `always` (0) or `when-required` (1).
+     * Sets the visibility of the vertical scrollbar. Can be `always` or `when-required`.
+     * Defaults to `when-required`.
      * @param value - The vertical scrollbar visibility.
      */
-    set verticalScrollbarVisibility(value: number) {
+    set verticalScrollbarVisibility(value: 'always' | 'when-required') {
         this._verticalScrollbarVisibility = value;
         if (this.component) {
-            this.component.verticalScrollbarVisibility = value;
+            this.component.verticalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -380,31 +382,31 @@ class ScrollViewComponentElement extends ComponentElement {
 
         switch (name) {
             case 'horizontal':
-                this.horizontal = newValue !== 'false';
+                this.horizontal = parseBool(newValue, true);
                 break;
             case 'vertical':
-                this.vertical = newValue !== 'false';
+                this.vertical = parseBool(newValue, true);
                 break;
             case 'scroll-mode':
-                this.scrollMode = parseEnum(newValue, scrollModes, SCROLL_MODE_BOUNCE);
+                this.scrollMode = parseEnum(newValue, scrollModes, 'bounce', name);
                 break;
             case 'bounce-amount':
-                this.bounceAmount = Number(newValue);
+                this.bounceAmount = parseNumber(newValue, 0.1, name);
                 break;
             case 'friction':
-                this.friction = Number(newValue);
+                this.friction = parseNumber(newValue, 0.05, name);
                 break;
             case 'use-mouse-wheel':
-                this.useMouseWheel = newValue !== 'false';
+                this.useMouseWheel = parseBool(newValue, true);
                 break;
             case 'mouse-wheel-sensitivity':
-                this.mouseWheelSensitivity = parseVec2(newValue);
+                this.mouseWheelSensitivity = parseVec2(newValue, Vec2.ONE, name);
                 break;
             case 'horizontal-scrollbar-visibility':
-                this.horizontalScrollbarVisibility = parseEnum(newValue, visibilities, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED);
+                this.horizontalScrollbarVisibility = parseEnum(newValue, visibilities, 'when-required', name);
                 break;
             case 'vertical-scrollbar-visibility':
-                this.verticalScrollbarVisibility = parseEnum(newValue, visibilities, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED);
+                this.verticalScrollbarVisibility = parseEnum(newValue, visibilities, 'when-required', name);
                 break;
             case 'viewport':
                 this.viewport = newValue;
@@ -424,4 +426,10 @@ class ScrollViewComponentElement extends ComponentElement {
 
 customElements.define('pc-scrollview', ScrollViewComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scrollview': ScrollViewComponentElement;
+    }
+}
+
 export { ScrollViewComponentElement };

package/src/components/sound-component.ts

@@ -1,6 +1,7 @@
 import { SoundComponent } from 'playcanvas';
 
 import { ComponentElement } from './component';
+import { parseBool, parseEnum, parseNumber } from '../utils';
 
 /**
  * The SoundComponentElement interface provides properties and methods for manipulating
@@ -46,8 +47,8 @@ class SoundComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas sound component.
      * @returns The sound component.
      */
-    get component(): SoundComponent | null {
-        return super.component as SoundComponent | null;
+    get component(): SoundComponent {
+        return super.component as SoundComponent;
     }
 
     /**
@@ -201,25 +202,25 @@ class SoundComponentElement extends ComponentElement {
 
         switch (name) {
             case 'distance-model':
-                this.distanceModel = newValue as 'exponential' | 'inverse' | 'linear';
+                this.distanceModel = parseEnum(newValue, ['exponential', 'inverse', 'linear'], 'linear', name);
                 break;
             case 'max-distance':
-                this.maxDistance = parseFloat(newValue);
+                this.maxDistance = parseNumber(newValue, 10000, name);
                 break;
             case 'pitch':
-                this.pitch = parseFloat(newValue);
+                this.pitch = parseNumber(newValue, 1, name);
                 break;
             case 'positional':
-                this.positional = this.hasAttribute('positional');
+                this.positional = parseBool(newValue, false);
                 break;
             case 'ref-distance':
-                this.refDistance = parseFloat(newValue);
+                this.refDistance = parseNumber(newValue, 1, name);
                 break;
             case 'roll-off-factor':
-                this.rollOffFactor = parseFloat(newValue);
+                this.rollOffFactor = parseNumber(newValue, 1, name);
                 break;
             case 'volume':
-                this.volume = parseFloat(newValue);
+                this.volume = parseNumber(newValue, 1, name);
                 break;
         }
     }
@@ -227,4 +228,10 @@ class SoundComponentElement extends ComponentElement {
 
 customElements.define('pc-sounds', SoundComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sounds': SoundComponentElement;
+    }
+}
+
 export { SoundComponentElement };

package/src/components/sound-slot.ts

@@ -3,6 +3,7 @@ import { SoundSlot } from 'playcanvas';
 import { AssetElement } from '../asset';
 import { AsyncElement } from '../async-element';
 import { SoundComponentElement } from './sound-component';
+import { parseBool, parseNumber } from '../utils';
 
 /**
  * The SoundSlotElement interface provides properties and methods for manipulating
@@ -58,14 +59,16 @@ class SoundSlotElement extends AsyncElement {
     }
 
     disconnectedCallback() {
-        this.soundElement!.component!.removeSlot(this._name);
+        // The component is null if the parent <pc-sound> (or the whole <pc-app>) is being
+        // torn down — parents disconnect first and have already removed the component.
+        this.soundElement?.component?.removeSlot(this._name);
     }
 
     protected get soundElement(): SoundComponentElement | null {
         const soundElement = this.parentElement as SoundComponentElement;
 
         if (!(soundElement instanceof SoundComponentElement)) {
-            console.warn('pc-sound-slot must be a direct child of a pc-sound element');
+            console.warn('pc-sound must be a direct child of a pc-sounds element');
             return null;
         }
 
@@ -114,12 +117,12 @@ class SoundSlotElement extends AsyncElement {
     }
 
     /**
-     * Sets the duration of the sound slot.
+     * Sets the duration of the sound slot, in seconds (or `null` to play the whole clip).
      * @param value - The duration.
      */
-    set duration(value: number) {
+    set duration(value: number | null) {
         this._duration = value;
-        if (this.soundSlot) {
+        if (this.soundSlot && value !== null) {
             this.soundSlot.duration = value;
         }
     }
@@ -128,8 +131,8 @@ class SoundSlotElement extends AsyncElement {
      * Gets the duration of the sound slot.
      * @returns The duration.
      */
-    get duration() {
-        return this._duration as number;
+    get duration(): number | null {
+        return this._duration;
     }
 
     /**
@@ -256,28 +259,28 @@ class SoundSlotElement extends AsyncElement {
                 this.asset = newValue;
                 break;
             case 'auto-play':
-                this.autoPlay = this.hasAttribute('auto-play');
+                this.autoPlay = parseBool(newValue, false);
                 break;
             case 'duration':
-                this.duration = parseFloat(newValue);
+                this.duration = parseNumber(newValue, null, name);
                 break;
             case 'loop':
-                this.loop = this.hasAttribute('loop');
+                this.loop = parseBool(newValue, false);
                 break;
             case 'name':
                 this.name = newValue;
                 break;
             case 'overlap':
-                this.overlap = this.hasAttribute('overlap');
+                this.overlap = parseBool(newValue, false);
                 break;
             case 'pitch':
-                this.pitch = parseFloat(newValue);
+                this.pitch = parseNumber(newValue, 1, name);
                 break;
             case 'start-time':
-                this.startTime = parseFloat(newValue);
+                this.startTime = parseNumber(newValue, 0, name);
                 break;
             case 'volume':
-                this.volume = parseFloat(newValue);
+                this.volume = parseNumber(newValue, 1, name);
                 break;
         }
     }
@@ -285,4 +288,10 @@ class SoundSlotElement extends AsyncElement {
 
 customElements.define('pc-sound', SoundSlotElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sound': SoundSlotElement;
+    }
+}
+
 export { SoundSlotElement };