@playcanvas/web-components 0.8.2 → 0.9.0

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

@@ -2,7 +2,7 @@ import { ScriptComponent } from 'playcanvas';
 import { ComponentElement } from './component';
 interface ScriptAttributesChangeEvent extends CustomEvent {
     detail: {
-        attributes: any;
+        attributes: Record<string, any>;
     };
 }
 interface ScriptEnableChangeEvent extends CustomEvent {
@@ -10,10 +10,17 @@ interface ScriptEnableChangeEvent extends CustomEvent {
         enabled: boolean;
     };
 }
+interface ScriptNameChangeEvent extends CustomEvent {
+    detail: {
+        oldName: string;
+        newName: string;
+    };
+}
 declare global {
     interface HTMLElementEventMap {
         'scriptattributeschange': ScriptAttributesChangeEvent;
         'scriptenablechange': ScriptEnableChangeEvent;
+        'scriptnamechange': ScriptNameChangeEvent;
     }
 }
 /**
@@ -28,41 +35,129 @@ declare class ScriptComponentElement extends ComponentElement {
     private observer;
     /** @ignore */
     constructor();
+    connectedCallback(): Promise<void>;
     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)
+     * - "asset:id" → the Asset created by the `pc-asset` element with that id
+     * - "entity:ref" → the Entity backing a `pc-entity` element. The reference can be a CSS
+     *   selector, an element id or an entity name.
+     * - "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)
+     *
+     * A prefixed string that fails to resolve or parse logs a warning and is left as the raw
+     * string.
      * @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.
+     * Recursively merge properties from source into target. When the target value is a Vec2,
+     * Vec3, Vec4 or Color and the source value is a plain numeric array, the array is converted
+     * to the target's type — so script attributes with math-typed defaults can be written as
+     * plain JSON arrays (e.g. `"focusPoint": [0, 1.75, 0]`).
      * @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.
+     * Checks whether a value is one of the math types that plain numeric arrays convert to.
+     * @param value - The value to check.
+     * @returns Whether the value is a math type.
+     */
+    private isMathType;
+    /**
+     * Converts a plain numeric array to the math type of `current`. A 3-element array targeting
+     * a Quat is interpreted as Euler angles in degrees, mirroring the `parseQuat` attribute
+     * grammar. Returns `null` (and logs a warning) when the array's length or contents don't
+     * match the type.
+     * @param current - The current (typed) value of the property.
+     * @param value - The incoming array.
+     * @param key - The property name, used in the warning message.
+     * @returns The converted value, or `null`.
+     */
+    private arrayToMathType;
+    /**
+     * Update script attributes by merging converted values into the script. `enabled` is always
+     * excluded (it is configured through the element's `enabled` attribute, not the JSON blob),
+     * as are any keys in `exclude` — used to keep per-property attributes authoritative over
+     * the blob without writing a property twice.
      * @param script - The script to update.
      * @param attributes - The attributes to merge into the script.
+     * @param exclude - Keys to strip from the merge.
      */
     private applyAttributes;
+    /**
+     * Returns the camelCase keys of the per-property attributes present on a `pc-script`
+     * element.
+     * @param scriptElement - The `pc-script` element.
+     * @returns The camelCase keys.
+     */
+    private inlineKeys;
+    /**
+     * Resolves the script instance owned by a `pc-script` element. Returns `null` when the
+     * element has no created script, or when its name resolves to a script created by a
+     * different element (e.g. a duplicate-named sibling).
+     * @param scriptElement - The `pc-script` element.
+     * @returns The owned script, or `null`.
+     */
+    private scriptFor;
     private handleScriptAttributesChange;
     private handleScriptEnableChange;
+    /**
+     * Handles a runtime `name` change on a child `pc-script`, swapping the engine script instance
+     * to match. Without this the element would keep pointing at the old-name instance: the old
+     * script would go on running while every subsequent update (attribute changes, enable
+     * changes, destruction on removal) resolved the new name and silently no-opped.
+     *
+     * The new instance is built by the normal creation path, so both attribute channels are
+     * re-applied to it and the declared enabled state is restored.
+     * @param event - The name change event.
+     */
+    private handleScriptNameChange;
+    /**
+     * Creates the script instance for a `pc-script` element. The instance is created disabled,
+     * the element's converted attributes are merged over the instance's defaults (which is what
+     * allows plain numeric arrays to be typed against those defaults), and only then is the
+     * declared enabled state applied — so `initialize()` runs with every attribute in place.
+     * @param scriptElement - The `pc-script` element to create the script instance for.
+     * @returns The created script, or `null`.
+     */
     private createScript;
+    /**
+     * Applies the per-property attributes present on a `pc-script` element — any attribute that
+     * is not part of the element's own API or a reserved HTML attribute name. These are applied
+     * after the `attributes` JSON, so an individual attribute always takes precedence over the
+     * blob.
+     * @param script - The script to apply the attributes to.
+     * @param scriptElement - The `pc-script` element holding the attributes.
+     */
+    private applyInlineAttributes;
+    /**
+     * Applies a single per-property attribute change to the script of a `pc-script` element.
+     * When the attribute has been removed, the value from the `attributes` JSON (if any) takes
+     * effect again.
+     * @param scriptElement - The `pc-script` element whose attribute changed.
+     * @param attributeName - The name of the changed attribute.
+     */
+    private applyScriptProperty;
+    /**
+     * Applies one attribute string to a script property. A string-typed attribute takes the
+     * value verbatim (so literals like 'color:red' are never hijacked by prefix conversion).
+     * Otherwise, explicit prefixes (`asset:`, `entity:`, `vec2:`, `vec3:`, `vec4:`, `color:`)
+     * carry their own type, and unprefixed values are parsed according to the type of the
+     * attribute's current value. The Script API itself (methods, `entity`, `app`) is never
+     * overwritten, invalid values keep the current value, and exceptions thrown by user
+     * getters/setters are contained so one bad attribute cannot abort the rest of a batch.
+     * @param script - The script to apply the value to.
+     * @param scriptName - The script name, used in warning messages.
+     * @param attributeName - The (kebab-case) element attribute name.
+     * @param value - The attribute value.
+     */
+    private setScriptProperty;
     private destroyScript;
     private handleMutations;
     disconnectedCallback(): void;
@@ -70,6 +165,11 @@ declare class ScriptComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas script component.
      * @returns The script component.
      */
-    get component(): ScriptComponent | null;
+    get component(): ScriptComponent;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scripts': ScriptComponentElement;
+    }
 }
 export { ScriptComponentElement };

package/dist/components/script.d.ts

@@ -1,22 +1,59 @@
+import { Script } from 'playcanvas';
+import { AsyncElement } from '../async-element';
 /**
  * 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.
  */
-declare class ScriptElement extends HTMLElement {
+declare class ScriptElement extends AsyncElement {
     private _attributes;
     private _enabled;
-    private _name;
     /**
-     * Sets the attributes of the script.
+     * 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;
+    /**
+     * The Script instance created for this element by its parent `<pc-scripts>` element.
+     * @ignore
+     */
+    _script: Script | 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);
+    set scriptAttributes(value: Record<string, any>);
     /**
      * Gets the attributes of the script.
      * @returns The attributes of the script.
      */
-    get scriptAttributes(): string;
+    get scriptAttributes(): Record<string, any>;
     /**
      * Sets the enabled state of the script.
      * @param value - The enabled state of the script.
@@ -28,7 +65,16 @@ declare class ScriptElement extends HTMLElement {
      */
     get enabled(): boolean;
     /**
-     * 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);
@@ -37,7 +83,25 @@ declare class ScriptElement extends HTMLElement {
      * @returns The name.
      */
     get name(): string;
+    /**
+     * 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;
+    connectedCallback(): void;
+    /**
+     * Called by the parent `<pc-scripts>` element when the script instance has been created.
+     * @ignore
+     */
+    _onScriptCreated(): void;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-script': ScriptElement;
+    }
 }
 export { ScriptElement };

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

@@ -20,17 +20,18 @@ declare class ScrollbarComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas scrollbar component.
      * @returns The scrollbar component.
      */
-    get component(): ScrollbarComponent | null;
+    get component(): 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');
     /**
      * Gets the orientation of the scrollbar.
      * @returns The orientation.
      */
-    get orientation(): number;
+    get orientation(): "horizontal" | "vertical";
     /**
      * Sets the current position value of the scrollbar, in the range 0 to 1.
      * @param value - The scrollbar value.
@@ -65,4 +66,9 @@ declare class ScrollbarComponentElement extends ComponentElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scrollbar': ScrollbarComponentElement;
+    }
+}
 export { ScrollbarComponentElement };

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

@@ -29,7 +29,7 @@ declare class ScrollViewComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas scroll view component.
      * @returns The scroll view component.
      */
-    get component(): ScrollViewComponent | null;
+    get component(): ScrollViewComponent;
     /**
      * Sets whether horizontal scrolling is enabled.
      * @param value - Whether horizontal scrolling is enabled.
@@ -52,15 +52,15 @@ declare class ScrollViewComponentElement extends ComponentElement {
     get vertical(): boolean;
     /**
      * 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');
     /**
      * Gets how the scroll view behaves when the content is scrolled beyond its bounds.
      * @returns The scroll mode.
      */
-    get scrollMode(): number;
+    get scrollMode(): "clamp" | "bounce" | "infinite";
     /**
      * Sets how far the content is allowed to bounce beyond its bounds when `scroll-mode` is
      * `bounce`, in the range 0 to 1.
@@ -104,25 +104,27 @@ declare class ScrollViewComponentElement extends ComponentElement {
      */
     get mouseWheelSensitivity(): Vec2;
     /**
-     * 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');
     /**
      * Gets the visibility of the horizontal scrollbar.
      * @returns The horizontal scrollbar visibility.
      */
-    get horizontalScrollbarVisibility(): number;
+    get horizontalScrollbarVisibility(): "always" | "when-required";
     /**
-     * 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');
     /**
      * Gets the visibility of the vertical scrollbar.
      * @returns The vertical scrollbar visibility.
      */
-    get verticalScrollbarVisibility(): number;
+    get verticalScrollbarVisibility(): "always" | "when-required";
     /**
      * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
      * viewport, which clips the content to the scroll view's bounds.
@@ -170,4 +172,9 @@ declare class ScrollViewComponentElement extends ComponentElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scrollview': ScrollViewComponentElement;
+    }
+}
 export { ScrollViewComponentElement };

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

@@ -31,7 +31,7 @@ declare class SoundComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas sound component.
      * @returns The sound component.
      */
-    get component(): SoundComponent | null;
+    get component(): SoundComponent;
     /**
      * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
      * @param value - The distance model.
@@ -105,4 +105,9 @@ declare class SoundComponentElement extends ComponentElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sounds': SoundComponentElement;
+    }
+}
 export { SoundComponentElement };

package/dist/components/sound-slot.d.ts

@@ -44,15 +44,15 @@ declare class SoundSlotElement extends AsyncElement {
      */
     get autoPlay(): boolean;
     /**
-     * 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);
     /**
      * Gets the duration of the sound slot.
      * @returns The duration.
      */
-    get duration(): number;
+    get duration(): number | null;
     /**
      * Sets the loop flag of the sound slot.
      * @param value - The loop flag.
@@ -116,4 +116,9 @@ declare class SoundSlotElement extends AsyncElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sound': SoundSlotElement;
+    }
+}
 export { SoundSlotElement };

package/dist/entity.d.ts

@@ -35,14 +35,21 @@ declare class EntityElement extends AsyncElement {
      * The pointer event listeners for the entity.
      */
     private _listeners;
+    /**
+     * The event types for which an inline `onpointer*` attribute is currently present.
+     */
+    private _inlineHandlerTypes;
     /**
      * Whether the hierarchy has been built for this entity.
      */
     private _built;
+    private _entity;
     /**
-     * The PlayCanvas entity instance.
+     * The PlayCanvas entity instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The entity instance.
      */
-    entity: Entity | null;
+    get entity(): Entity;
     createEntity(app: AppBase): void;
     buildHierarchy(app: AppBase): void;
     connectedCallback(): void;
@@ -107,10 +114,27 @@ declare class EntityElement extends AsyncElement {
      * @returns The tags of the entity.
      */
     get tags(): string[];
+    /**
+     * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+     * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
+     * the previous handler and removing it removes the handler, exactly like `onclick` on any
+     * HTML element. But because they bypass {@link addEventListener}, the connect/disconnect
+     * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
+     * kept in sync here.
+     *
+     * @param name - The attribute name (e.g. 'onpointerdown').
+     * @param value - The attribute value, or `null` when the attribute has been removed.
+     */
+    private _updateInlineHandler;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
     addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
     removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
     hasListeners(type: string): boolean;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-entity': EntityElement;
+    }
+}
 export { EntityElement };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module EngineWebComponents
  */
-import { AsyncElement } from './async-element';
+import { AsyncElement, whenReady } from './async-element';
 import { ModuleElement } from './module';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
@@ -35,4 +35,5 @@ import { MaterialElement } from './material';
 import { ModelElement } from './model';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
-export { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, MaterialElement, ModelElement, SceneElement, SkyElement };
+export { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, ButtonComponentElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, LayoutChildComponentElement, LayoutGroupComponentElement, ParticleSystemComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScrollbarComponentElement, ScrollViewComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, GSplatComponentElement, MaterialElement, ModelElement, SceneElement, SkyElement, whenReady };
+export type { AsyncElementTagName } from './async-element';

package/dist/material.d.ts

@@ -4,6 +4,10 @@ import { Color, StandardMaterial } from 'playcanvas';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-material/ | `<pc-material>`} elements.
  * The MaterialElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * A `pc-material` must be a direct child of `pc-app` — elements placed elsewhere log a warning
+ * and never create a material. Elements inserted while the application is already running are
+ * created on insertion.
  */
 declare class MaterialElement extends HTMLElement {
     private _diffuse;
@@ -12,6 +16,7 @@ declare class MaterialElement extends HTMLElement {
     private _normalMap;
     private _roughnessMap;
     material: StandardMaterial | null;
+    connectedCallback(): Promise<void>;
     createMaterial(): void;
     disconnectedCallback(): void;
     setMap(map: string, property: 'diffuseMap' | 'metalnessMap' | 'normalMap' | 'glossMap'): void;
@@ -29,4 +34,9 @@ declare class MaterialElement extends HTMLElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-material': MaterialElement;
+    }
+}
 export { MaterialElement };

package/dist/model.d.ts

@@ -26,4 +26,9 @@ declare class ModelElement extends AsyncElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-model': ModelElement;
+    }
+}
 export { ModelElement };

package/dist/module.d.ts

@@ -11,4 +11,9 @@ declare class ModuleElement extends HTMLElement {
     private loadModule;
     getLoadPromise(): Promise<void>;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-module': ModuleElement;
+    }
+}
 export { ModuleElement };