@playcanvas/web-components 0.20.0 → 0.21.0

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class ScrollbarComponentElement extends ComponentElement {
+declare class ScrollbarComponentElement extends ComponentElement<ScrollbarComponent> {
     private _orientation;
     private _value;
     private _handleSize;
@@ -23,10 +23,11 @@ declare class ScrollbarComponentElement extends ComponentElement {
     constructor();
     protected getInitialComponentData(): Record<string, any>;
     /**
-     * Gets the underlying PlayCanvas scrollbar component.
-     * @returns The scrollbar component.
+     * Gets the underlying PlayCanvas scrollbar component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scrollbar component, or `null`.
      */
-    get component(): ScrollbarComponent;
+    get component(): ScrollbarComponent | null;
     /**
      * Sets the orientation of the scrollbar. Can be `horizontal` or `vertical`. Defaults to
      * `horizontal`.

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.cjs';
  *
  * @category Components
  */
-declare class SoundComponentElement extends ComponentElement {
+declare class SoundComponentElement extends ComponentElement<SoundComponent> {
     private _distanceModel;
     private _maxDistance;
     private _pitch;
@@ -34,10 +34,11 @@ declare class SoundComponentElement extends ComponentElement {
         volume: number;
     };
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
-    get component(): SoundComponent;
+    get component(): SoundComponent | null;
     /**
      * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
      * @param value - The distance model.

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

@@ -14,7 +14,7 @@ import { ComponentElement } from './component.js';
  *
  * @category Components
  */
-declare class SoundComponentElement extends ComponentElement {
+declare class SoundComponentElement extends ComponentElement<SoundComponent> {
     private _distanceModel;
     private _maxDistance;
     private _pitch;
@@ -34,10 +34,11 @@ declare class SoundComponentElement extends ComponentElement {
         volume: number;
     };
     /**
-     * Gets the underlying PlayCanvas sound component.
-     * @returns The sound component.
+     * Gets the underlying PlayCanvas sound component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The sound component, or `null`.
      */
-    get component(): SoundComponent;
+    get component(): SoundComponent | null;
     /**
      * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
      * @param value - The distance model.

package/dist/custom-elements.json

@@ -6490,9 +6490,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "AnimComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas anim component.",
+              "description": "Gets the underlying PlayCanvas anim component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -6761,9 +6761,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "AudioListenerComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas audio listener component.",
+              "description": "Gets the underlying PlayCanvas audio listener component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -6931,9 +6931,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ButtonComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas button component.",
+              "description": "Gets the underlying PlayCanvas button component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -7524,9 +7524,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "CameraComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas camera component.",
+              "description": "Gets the underlying PlayCanvas camera component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -8157,9 +8157,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "CollisionComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas collision component.",
+              "description": "Gets the underlying PlayCanvas collision component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -8629,9 +8629,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ElementComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas element component.",
+              "description": "Gets the underlying PlayCanvas element component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -9366,9 +9366,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "GSplatComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas gsplat component.",
+              "description": "Gets the underlying PlayCanvas gsplat component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -9797,9 +9797,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "JointComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas joint component.",
+              "description": "Gets the underlying PlayCanvas joint component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -10546,9 +10546,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "LayoutChildComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas layout child component.",
+              "description": "Gets the underlying PlayCanvas layout child component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -10889,9 +10889,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "LayoutGroupComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas layout group component.",
+              "description": "Gets the underlying PlayCanvas layout group component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -11316,9 +11316,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "LightComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas light component.",
+              "description": "Gets the underlying PlayCanvas light component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -11975,9 +11975,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ParticleSystemComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas particle system component.",
+              "description": "Gets the underlying PlayCanvas particle system component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -12176,9 +12176,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "RenderComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas render component.",
+              "description": "Gets the underlying PlayCanvas render component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -12427,9 +12427,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "RigidBodyComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas rigidbody component.",
+              "description": "Gets the underlying PlayCanvas rigidbody component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -12683,9 +12683,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ScreenComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas screen component.",
+              "description": "Gets the underlying PlayCanvas screen component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -12937,9 +12937,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ScriptComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas script component.",
+              "description": "Gets the underlying PlayCanvas script component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -13321,9 +13321,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ScrollViewComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas scroll view component.",
+              "description": "Gets the underlying PlayCanvas scroll view component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -13780,9 +13780,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "ScrollbarComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas scrollbar component.",
+              "description": "Gets the underlying PlayCanvas scrollbar component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""
@@ -14033,9 +14033,9 @@
               "kind": "field",
               "name": "component",
               "type": {
-                "text": "Component | null"
+                "text": "SoundComponent | null"
               },
-              "description": "Gets the underlying PlayCanvas sound component.",
+              "description": "Gets the underlying PlayCanvas sound component. `null` until the element is\nready — see ComponentElement.component.",
               "return": {
                 "type": {
                   "text": ""

package/dist/entity-reference.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Resolves entity reference strings against the document. A reference beginning with `#` is a
+ * document-wide selector (an element id, or any selector rooted in one); anything else is an
+ * entity name, resolved lexically through the entity hierarchy first and against the document
+ * after — never as a selector or an id.
+ *
+ * Unlike the attribute parsers in `parse.ts`, these helpers touch the DOM, and `findEntityElement`
+ * and `getEntity` return `null` instead of falling back to a default. They also do not warn -
+ * what an unresolved reference means depends on the element holding it - so elements report
+ * through `resolveEntity`, which takes that meaning as parameters, and `pc-script` builds its own
+ * message from the lower-level pieces.
+ */
+export {};

package/dist/entity-reference.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves entity reference strings against the document. A reference beginning with `#` is a
+ * document-wide selector (an element id, or any selector rooted in one); anything else is an
+ * entity name, resolved lexically through the entity hierarchy first and against the document
+ * after — never as a selector or an id.
+ *
+ * Unlike the attribute parsers in `parse.ts`, these helpers touch the DOM, and `findEntityElement`
+ * and `getEntity` return `null` instead of falling back to a default. They also do not warn -
+ * what an unresolved reference means depends on the element holding it - so elements report
+ * through `resolveEntity`, which takes that meaning as parameters, and `pc-script` builds its own
+ * message from the lower-level pieces.
+ */
+export {};

package/dist/material.d.cts

@@ -130,11 +130,12 @@ declare class MaterialElement extends HTMLElement {
     private _useSkybox;
     private _useTonemap;
     /**
-     * Pending `load` handlers, one per texture slot. A slot's handler is torn down when the slot is
-     * reassigned or the element disconnects, so a late-arriving asset can never write a texture the
-     * element no longer wants.
+     * One asset binding per texture slot, created on first use and kept for the element's
+     * lifetime. A slot's binding is superseded when the slot is reassigned and cancelled when the
+     * element disconnects, so a late-arriving asset can never write a texture the element no
+     * longer wants.
      */
-    private _mapHandles;
+    private _mapBindings;
     private _updateScheduled;
     private _glossConflictWarned;
     /**
@@ -163,8 +164,9 @@ declare class MaterialElement extends HTMLElement {
      */
     private _warnGlossConflict;
     /**
-     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when it
-     * has not already. An empty id clears the slot.
+     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when
+     * it has not already. An empty id clears the slot; a slot keeps its current texture while
+     * the new asset loads, and also across a failed load - a later reload can still deliver.
      *
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.

package/dist/material.d.ts

@@ -130,11 +130,12 @@ declare class MaterialElement extends HTMLElement {
     private _useSkybox;
     private _useTonemap;
     /**
-     * Pending `load` handlers, one per texture slot. A slot's handler is torn down when the slot is
-     * reassigned or the element disconnects, so a late-arriving asset can never write a texture the
-     * element no longer wants.
+     * One asset binding per texture slot, created on first use and kept for the element's
+     * lifetime. A slot's binding is superseded when the slot is reassigned and cancelled when the
+     * element disconnects, so a late-arriving asset can never write a texture the element no
+     * longer wants.
      */
-    private _mapHandles;
+    private _mapBindings;
     private _updateScheduled;
     private _glossConflictWarned;
     /**
@@ -163,8 +164,9 @@ declare class MaterialElement extends HTMLElement {
      */
     private _warnGlossConflict;
     /**
-     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when it
-     * has not already. An empty id clears the slot.
+     * Points a texture slot at the resource of a `pc-asset`, waiting for the asset to load when
+     * it has not already. An empty id clears the slot; a slot keeps its current texture while
+     * the new asset loads, and also across a failed load - a later reload can still deliver.
      *
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.

package/dist/model.d.cts

@@ -120,18 +120,18 @@ declare class ModelElement extends EntityOwnerElement {
     private _contentEntity;
     /**
      * Incremented on every new load, on disconnect, and when the host entity dies, and captured
-     * by a load when it starts. A load that resumes from an await or a load callback abandons
-     * itself if the value has moved on, so a superseded load can neither instantiate a second
-     * content root nor parent one under a host a newer cycle has already replaced.
+     * by a load when it starts. A load that resumes from an await abandons itself if the value
+     * has moved on, so a superseded load can neither instantiate a second content root nor
+     * parent one under a host a newer cycle has already replaced. The asset subscription itself
+     * is guarded by the binding below.
      */
     private _loadGeneration;
     /**
-     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
-     * so that whatever supersedes the load can detach the handlers from the asset, rather than
-     * leave them registered until the asset settles (or forever, if it never does).
+     * The subscription to the current container asset while it is loading. Whatever supersedes
+     * the load — a newer load, a disconnect, the host dying — cancels it, so the asset settling
+     * later cannot deliver to a load that no longer owns the element.
      */
-    private _loadHandle;
-    private _errorHandle;
+    private _binding;
     /**
      * The root entity of the instantiated model content, parented beneath the host entity.
      * `null` until the container asset has loaded and been instantiated, after a failed load,
@@ -170,7 +170,6 @@ declare class ModelElement extends EntityOwnerElement {
      * @param entity - The host entity that was destroyed.
      */
     protected _onEntityDestroy(entity: Entity): void;
-    private _detachLoadHandlers;
     /**
      * Resolves readiness and dispatches the `load` event. Called once the instantiated content
      * has been parented beneath the host — the host itself is already in the scene graph by

package/dist/model.d.ts

@@ -120,18 +120,18 @@ declare class ModelElement extends EntityOwnerElement {
     private _contentEntity;
     /**
      * Incremented on every new load, on disconnect, and when the host entity dies, and captured
-     * by a load when it starts. A load that resumes from an await or a load callback abandons
-     * itself if the value has moved on, so a superseded load can neither instantiate a second
-     * content root nor parent one under a host a newer cycle has already replaced.
+     * by a load when it starts. A load that resumes from an await abandons itself if the value
+     * has moved on, so a superseded load can neither instantiate a second content root nor
+     * parent one under a host a newer cycle has already replaced. The asset subscription itself
+     * is guarded by the binding below.
      */
     private _loadGeneration;
     /**
-     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
-     * so that whatever supersedes the load can detach the handlers from the asset, rather than
-     * leave them registered until the asset settles (or forever, if it never does).
+     * The subscription to the current container asset while it is loading. Whatever supersedes
+     * the load — a newer load, a disconnect, the host dying — cancels it, so the asset settling
+     * later cannot deliver to a load that no longer owns the element.
      */
-    private _loadHandle;
-    private _errorHandle;
+    private _binding;
     /**
      * The root entity of the instantiated model content, parented beneath the host entity.
      * `null` until the container asset has loaded and been instantiated, after a failed load,
@@ -170,7 +170,6 @@ declare class ModelElement extends EntityOwnerElement {
      * @param entity - The host entity that was destroyed.
      */
     protected _onEntityDestroy(entity: Entity): void;
-    private _detachLoadHandlers;
     /**
      * Resolves readiness and dispatches the `load` event. Called once the instantiated content
      * has been parented beneath the host — the host itself is already in the scene graph by

package/dist/parse.d.cts

@@ -11,13 +11,5 @@
  *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
  * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
  *   so they never warn.
- *
- * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference rather than
- * parsing a literal, and return `null` instead of falling back to a default. A reference
- * beginning with `#` is a document-wide selector (an element id, or any selector rooted in one);
- * anything else is an entity name, resolved lexically through the entity hierarchy first and
- * against the document after — never as a selector or an id. They also do not warn - what an
- * unresolved reference means depends on the element holding it - so elements report through
- * `resolveEntity`, which takes that meaning as parameters.
  */
 export {};

package/dist/parse.d.ts

@@ -11,13 +11,5 @@
  *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
  * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
  *   so they never warn.
- *
- * `findEntityElement` and `getEntity` are the exceptions: they resolve a reference rather than
- * parsing a literal, and return `null` instead of falling back to a default. A reference
- * beginning with `#` is a document-wide selector (an element id, or any selector rooted in one);
- * anything else is an entity name, resolved lexically through the entity hierarchy first and
- * against the document after — never as a selector or an id. They also do not warn - what an
- * unresolved reference means depends on the element holding it - so elements report through
- * `resolveEntity`, which takes that meaning as parameters.
  */
 export {};

package/dist/pointer-controller.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/pointer-controller.d.ts

@@ -0,0 +1 @@
+export {};