@playcanvas/web-components 0.10.1 → 0.11.1

package/src/components/script-component.ts

@@ -1,9 +1,21 @@
-import { Color, Quat, ScriptComponent, Script, Vec2, Vec3, Vec4 } from 'playcanvas';
+import type { ScriptComponent, Script } from 'playcanvas';
+import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { AssetElement } from '../asset';
+import {
+    getEntity,
+    parseBool,
+    parseColor,
+    parseComponents,
+    parseNumber,
+    parseQuat,
+    parseVec2,
+    parseVec3,
+    parseVec4
+} from '../parse';
+
 import { ComponentElement } from './component';
 import { ScriptElement } from './script';
-import { getEntity, parseBool, parseColor, parseComponents, parseNumber, parseQuat, parseVec2, parseVec3, parseVec4 } from '../parse';
 
 /**
  * Attributes on `pc-script` that never map to script attributes: the element's own API (derived
@@ -11,10 +23,34 @@ import { getEntity, parseBool, parseColor, parseComponents, parseNumber, parseQu
  */
 const RESERVED_ATTRIBUTES = new Set([
     ...ScriptElement.observedAttributes,
-    'accesskey', 'autocapitalize', 'autofocus', 'class', 'contenteditable', 'dir', 'draggable',
-    'exportparts', 'hidden', 'id', 'inert', 'is', 'itemid', 'itemprop', 'itemref', 'itemscope',
-    'itemtype', 'lang', 'nonce', 'part', 'popover', 'role', 'slot', 'spellcheck', 'style',
-    'tabindex', 'title', 'translate'
+    'accesskey',
+    'autocapitalize',
+    'autofocus',
+    'class',
+    'contenteditable',
+    'dir',
+    'draggable',
+    'exportparts',
+    'hidden',
+    'id',
+    'inert',
+    'is',
+    'itemid',
+    'itemprop',
+    'itemref',
+    'itemscope',
+    'itemtype',
+    'lang',
+    'nonce',
+    'part',
+    'popover',
+    'role',
+    'slot',
+    'spellcheck',
+    'style',
+    'tabindex',
+    'title',
+    'translate'
 ]);
 
 /**
@@ -27,11 +63,13 @@ const RESERVED_ATTRIBUTES = new Set([
  * @returns Whether the attribute name is reserved.
  */
 const isReservedAttribute = (name: string): boolean => {
-    return RESERVED_ATTRIBUTES.has(name) ||
+    return (
+        RESERVED_ATTRIBUTES.has(name) ||
         name.startsWith('data-') ||
         name.startsWith('aria-') ||
         name.startsWith('_') ||
-        (name.startsWith('on') && name in HTMLElement.prototype);
+        (name.startsWith('on') && name in HTMLElement.prototype)
+    );
 };
 
 /**
@@ -39,7 +77,14 @@ const isReservedAttribute = (name: string): boolean => {
  * the (optional, so possibly undefined) lifecycle methods.
  */
 const SCRIPT_API_MEMBERS = new Set([
-    'app', 'entity', 'destroy', 'initialize', 'postInitialize', 'postUpdate', 'swap', 'update'
+    'app',
+    'entity',
+    'destroy',
+    'initialize',
+    'postInitialize',
+    'postUpdate',
+    'swap',
+    'update'
 ]);
 
 /**
@@ -57,7 +102,7 @@ const kebabToCamel = (name: string): string => {
  * @returns The kebab-case name.
  */
 const camelToKebab = (name: string): string => {
-    return name.replace(/[A-Z]/g, char => `-${char.toLowerCase()}`);
+    return name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 };
 
 /**
@@ -110,7 +155,9 @@ const vectorConversion = (length: 2 | 3 | 4, Ctor: new (components: number[]) =>
         if (components) {
             return new Ctor(components);
         }
-        console.warn(`Invalid script attribute value '${raw}'. Expected ${length} space-separated numbers after 'vec${length}:'.`);
+        console.warn(
+            `Invalid script attribute value '${raw}'. Expected ${length} space-separated numbers after 'vec${length}:'.`
+        );
         return raw;
     };
 };
@@ -183,27 +230,17 @@ const findCaseMatch = (script: any, key: string): string | null => {
     return null;
 };
 
-// Add these interfaces at the top of the file, after the imports
-interface ScriptAttributesChangeEvent extends CustomEvent {
+export type ScriptAttributesChangeEvent = {
     detail: { attributes: Record<string, any> };
-}
+} & CustomEvent;
 
-interface ScriptEnableChangeEvent extends CustomEvent {
+export type ScriptEnableChangeEvent = {
     detail: { enabled: boolean };
-}
-
-interface ScriptNameChangeEvent extends CustomEvent {
-    detail: { oldName: string, newName: string };
-}
+} & CustomEvent;
 
-// Add this interface before the ScriptComponentElement class
-declare global {
-    interface HTMLElementEventMap {
-        'scriptattributeschange': ScriptAttributesChangeEvent;
-        'scriptenablechange': ScriptEnableChangeEvent;
-        'scriptnamechange': ScriptNameChangeEvent;
-    }
-}
+export type ScriptNameChangeEvent = {
+    detail: { oldName: string; newName: string };
+} & CustomEvent;
 
 /**
  * The ScriptComponentElement interface provides properties and methods for manipulating
@@ -237,7 +274,7 @@ class ScriptComponentElement extends ComponentElement {
         return super.connectedCallback();
     }
 
-    initComponent() {
+    protected initComponent() {
         // Handle initial script elements
         this.querySelectorAll<ScriptElement>(':scope > pc-script').forEach((scriptElement) => {
             this.createScript(scriptElement);
@@ -303,7 +340,12 @@ class ScriptComponentElement extends ComponentElement {
             // Only recurse into plain objects. Class instances (Vec3, Color, Asset, Entity...)
             // are leaf values assigned whole, so accessor-typed script attributes receive them
             // through their setters instead of having a getter's returned copy mutated.
-            if (value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype) {
+            if (
+                value &&
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                Object.getPrototypeOf(value) === Object.prototype
+            ) {
                 if (!current || typeof current !== 'object') {
                     target[key] = {};
                 }
@@ -321,7 +363,13 @@ class ScriptComponentElement extends ComponentElement {
      * @returns Whether the value is a math type.
      */
     private isMathType(value: any): value is Vec2 | Vec3 | Vec4 | Color | Quat {
-        return value instanceof Vec2 || value instanceof Vec3 || value instanceof Vec4 || value instanceof Color || value instanceof Quat;
+        return (
+            value instanceof Vec2 ||
+            value instanceof Vec3 ||
+            value instanceof Vec4 ||
+            value instanceof Color ||
+            value instanceof Quat
+        );
     }
 
     /**
@@ -334,15 +382,22 @@ class ScriptComponentElement extends ComponentElement {
      * @param key - The property name, used in the warning message.
      * @returns The converted value, or `null`.
      */
-    private arrayToMathType(current: Vec2 | Vec3 | Vec4 | Color | Quat, value: any[], key: string): Vec2 | Vec3 | Vec4 | Color | Quat | null {
-        if (value.every(component => typeof component === 'number' && Number.isFinite(component))) {
+    private arrayToMathType(
+        current: Vec2 | Vec3 | Vec4 | Color | Quat,
+        value: any[],
+        key: string
+    ): Vec2 | Vec3 | Vec4 | Color | Quat | null {
+        if (value.every((component) => typeof component === 'number' && Number.isFinite(component))) {
             if (current instanceof Vec2 && value.length === 2) return new Vec2(value);
             if (current instanceof Vec3 && value.length === 3) return new Vec3(value);
             if (current instanceof Vec4 && value.length === 4) return new Vec4(value);
             if (current instanceof Color && (value.length === 3 || value.length === 4)) return new Color(value);
-            if (current instanceof Quat && value.length === 3) return new Quat().setFromEulerAngles(value[0], value[1], value[2]);
+            if (current instanceof Quat && value.length === 3)
+                return new Quat().setFromEulerAngles(value[0], value[1], value[2]);
         }
-        console.warn(`Cannot convert script attribute '${key}' array [${value}] to ${current.constructor.name}. Keeping the current value.`);
+        console.warn(
+            `Cannot convert script attribute '${key}' array [${value}] to ${current.constructor.name}. Keeping the current value.`
+        );
         return null;
     }
 
@@ -540,7 +595,9 @@ class ScriptComponentElement extends ComponentElement {
             const current = script[key];
 
             if (typeof current === 'function' || SCRIPT_API_MEMBERS.has(key)) {
-                console.warn(`Ignoring attribute '${attributeName}' on pc-script '${scriptName}' - '${key}' is part of the Script API.`);
+                console.warn(
+                    `Ignoring attribute '${attributeName}' on pc-script '${scriptName}' - '${key}' is part of the Script API.`
+                );
                 return;
             }
 
@@ -570,14 +627,20 @@ class ScriptComponentElement extends ComponentElement {
             } else {
                 const match = findCaseMatch(script, key);
                 if (match) {
-                    console.warn(`Script '${scriptName}' has no attribute '${key}' - did you mean '${camelToKebab(match)}'? Attribute names are kebab-case.`);
+                    console.warn(
+                        `Script '${scriptName}' has no attribute '${key}' - did you mean '${camelToKebab(match)}'? Attribute names are kebab-case.`
+                    );
                     return;
                 }
-                console.warn(`Script '${scriptName}' has no typed attribute '${key}' - assigning the raw string from '${attributeName}'.`);
+                console.warn(
+                    `Script '${scriptName}' has no typed attribute '${key}' - assigning the raw string from '${attributeName}'.`
+                );
                 script[key] = value;
             }
         } catch (error) {
-            console.warn(`Error applying attribute '${attributeName}' to script '${scriptName}': ${(error as Error).message}`);
+            console.warn(
+                `Error applying attribute '${attributeName}' to script '${scriptName}': ${(error as Error).message}`
+            );
         }
     }
 
@@ -616,7 +679,12 @@ class ScriptComponentElement extends ComponentElement {
             mutation.removedNodes.forEach((node) => {
                 if (node instanceof ScriptElement) {
                     const scriptName = node.getAttribute('name');
-                    if (scriptName && node._script && this.component && this.component.get(scriptName) === node._script) {
+                    if (
+                        scriptName &&
+                        node._script &&
+                        this.component &&
+                        this.component.get(scriptName) === node._script
+                    ) {
                         this.destroyScript(scriptName);
                     }
                     node._script = null;
@@ -648,10 +716,4 @@ class ScriptComponentElement extends ComponentElement {
 
 customElements.define('pc-scripts', ScriptComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-scripts': ScriptComponentElement;
-    }
-}
-
 export { ScriptComponentElement };

package/src/components/script.ts

@@ -1,4 +1,4 @@
-import { Script } from 'playcanvas';
+import type { Script } from 'playcanvas';
 
 import { AsyncElement } from '../async-element';
 import { parseBool } from '../parse';
@@ -39,18 +39,11 @@ import { parseBool } from '../parse';
 class ScriptElement extends AsyncElement {
     private _attributes: Record<string, any> = {};
 
-    private _enabled: boolean = true;
-
-    /**
-     * 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;
+    private _enabled = true;
 
     /**
      * The Script instance created for this element by its parent `<pc-scripts>` element.
-     * @ignore
+     * @internal
      */
     _script: Script | null = null;
 
@@ -64,10 +57,12 @@ class ScriptElement extends AsyncElement {
      */
     set scriptAttributes(value: Record<string, any>) {
         this._attributes = value ?? {};
-        this.dispatchEvent(new CustomEvent('scriptattributeschange', {
-            detail: { attributes: this._attributes },
-            bubbles: true
-        }));
+        this.dispatchEvent(
+            new CustomEvent('scriptattributeschange', {
+                detail: { attributes: this._attributes },
+                bubbles: true
+            })
+        );
     }
 
     /**
@@ -84,10 +79,12 @@ class ScriptElement extends AsyncElement {
      */
     set enabled(value: boolean) {
         this._enabled = value;
-        this.dispatchEvent(new CustomEvent('scriptenablechange', {
-            detail: { enabled: value },
-            bubbles: true
-        }));
+        this.dispatchEvent(
+            new CustomEvent('scriptenablechange', {
+                detail: { enabled: value },
+                bubbles: true
+            })
+        );
     }
 
     /**
@@ -137,17 +134,27 @@ class ScriptElement extends AsyncElement {
         // 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`);
+            console.warn(
+                `pc-script '${this.getAttribute('name')}' must be a direct child of pc-scripts - script not created`
+            );
         }
     }
 
+    disconnectedCallback() {
+        // Re-arm readiness so a re-inserted element announces the instance created for it then.
+        // `_script` is deliberately NOT cleared here: the parent's mutation observer processes
+        // this removal afterwards and reads it to establish which engine script this element
+        // owned - the parent is what clears it.
+        this._resetReady();
+    }
+
     /**
      * Called by the parent `<pc-scripts>` element when the script instance has been created.
-     * @ignore
+     * Creation can happen more than once per connection (a runtime `name` change recreates the
+     * instance), but `_onReady` signals readiness at most once per cycle.
+     * @internal
      */
     _onScriptCreated() {
-        if (this._readySignalled) return;
-        this._readySignalled = true;
         this._onReady();
     }
 
@@ -165,7 +172,9 @@ class ScriptElement extends AsyncElement {
                 try {
                     this.scriptAttributes = JSON.parse(newValue);
                 } catch (error) {
-                    console.warn(`Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`);
+                    console.warn(
+                        `Invalid 'attributes' JSON on pc-script '${this.getAttribute('name')}': ${(error as Error).message}`
+                    );
                 }
                 break;
             case 'enabled':
@@ -176,10 +185,12 @@ class ScriptElement extends AsyncElement {
                 // 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
-                    }));
+                    this.dispatchEvent(
+                        new CustomEvent('scriptnamechange', {
+                            detail: { oldName: oldValue, newName: newValue },
+                            bubbles: true
+                        })
+                    );
                 }
                 break;
         }
@@ -188,10 +199,4 @@ class ScriptElement extends AsyncElement {
 
 customElements.define('pc-script', ScriptElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-script': ScriptElement;
-    }
-}
-
 export { ScriptElement };

package/src/components/scrollbar-component.ts

@@ -1,8 +1,10 @@
-import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL, ScrollbarComponent } from 'playcanvas';
+import type { ScrollbarComponent } from 'playcanvas';
+import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { getEntity, parseEnum, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 const orientations = new Map<'horizontal' | 'vertical', number>([
     ['horizontal', ORIENTATION_HORIZONTAL],
     ['vertical', ORIENTATION_VERTICAL]
@@ -30,7 +32,7 @@ class ScrollbarComponentElement extends ComponentElement {
         super('scrollbar');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             orientation: orientations.get(this._orientation),
             value: this._value,
@@ -133,13 +135,7 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [
-            ...super.observedAttributes,
-            'orientation',
-            'value',
-            'handle-size',
-            'handle'
-        ];
+        return [...super.observedAttributes, 'orientation', 'value', 'handle-size', 'handle'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -164,10 +160,4 @@ 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,8 +1,17 @@
-import { SCROLL_MODE_BOUNCE, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, ScrollViewComponent, Vec2 } from 'playcanvas';
+import type { ScrollViewComponent } from 'playcanvas';
+import {
+    SCROLL_MODE_BOUNCE,
+    SCROLL_MODE_CLAMP,
+    SCROLL_MODE_INFINITE,
+    SCROLLBAR_VISIBILITY_SHOW_ALWAYS,
+    SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED,
+    Vec2
+} from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
 
+import { ComponentElement } from './component';
+
 const scrollModes = new Map<'clamp' | 'bounce' | 'infinite', number>([
     ['clamp', SCROLL_MODE_CLAMP],
     ['bounce', SCROLL_MODE_BOUNCE],
@@ -54,7 +63,7 @@ class ScrollViewComponentElement extends ComponentElement {
         super('scrollview');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         const data: Record<string, any> = {
             horizontal: this._horizontal,
             vertical: this._vertical,
@@ -99,7 +108,8 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets whether horizontal scrolling is enabled.
+     * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
      * @param value - Whether horizontal scrolling is enabled.
      */
     set horizontal(value: boolean) {
@@ -110,7 +120,7 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets whether horizontal scrolling is enabled.
+     * Gets whether scrolling along the horizontal axis is enabled.
      * @returns Whether horizontal scrolling is enabled.
      */
     get horizontal() {
@@ -118,7 +128,8 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets whether vertical scrolling is enabled.
+     * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+     * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
      * @param value - Whether vertical scrolling is enabled.
      */
     set vertical(value: boolean) {
@@ -129,7 +140,7 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical() {
@@ -242,7 +253,8 @@ class ScrollViewComponentElement extends ComponentElement {
     set horizontalScrollbarVisibility(value: 'always' | 'when-required') {
         this._horizontalScrollbarVisibility = value;
         if (this.component) {
-            this.component.horizontalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+            this.component.horizontalScrollbarVisibility =
+                visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -262,7 +274,8 @@ class ScrollViewComponentElement extends ComponentElement {
     set verticalScrollbarVisibility(value: 'always' | 'when-required') {
         this._verticalScrollbarVisibility = value;
         if (this.component) {
-            this.component.verticalScrollbarVisibility = visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
+            this.component.verticalScrollbarVisibility =
+                visibilities.get(value) ?? SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED;
         }
     }
 
@@ -426,10 +439,4 @@ 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,8 +1,9 @@
-import { SoundComponent } from 'playcanvas';
+import type { SoundComponent } from 'playcanvas';
 
-import { ComponentElement } from './component';
 import { parseBool, parseEnum, parseNumber } from '../parse';
 
+import { ComponentElement } from './component';
+
 /**
  * The SoundComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-sounds/ | `<pc-sounds>`} elements.
@@ -14,24 +15,24 @@ import { parseBool, parseEnum, parseNumber } from '../parse';
 class SoundComponentElement extends ComponentElement {
     private _distanceModel: 'exponential' | 'inverse' | 'linear' = 'linear';
 
-    private _maxDistance: number = 10000;
+    private _maxDistance = 10000;
 
-    private _pitch: number = 1;
+    private _pitch = 1;
 
-    private _positional: boolean = false;
+    private _positional = false;
 
-    private _refDistance: number = 1;
+    private _refDistance = 1;
 
-    private _rollOffFactor: number = 1;
+    private _rollOffFactor = 1;
 
-    private _volume: number = 1;
+    private _volume = 1;
 
     /** @ignore */
     constructor() {
         super('sound');
     }
 
-    getInitialComponentData() {
+    protected getInitialComponentData() {
         return {
             distanceModel: this._distanceModel,
             maxDistance: this._maxDistance,
@@ -228,10 +229,4 @@ class SoundComponentElement extends ComponentElement {
 
 customElements.define('pc-sounds', SoundComponentElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-sounds': SoundComponentElement;
-    }
-}
-
 export { SoundComponentElement };