@playcanvas/web-components 0.11.1 → 0.12.0

package/dist/entity-base.d.ts

@@ -0,0 +1,67 @@
+import type { Entity } from 'playcanvas';
+import type { AppElement } from './app';
+import { AsyncElement } from './async-element';
+/**
+ * The attribute names of the inline `onpointer*` event handlers, shared by every element that
+ * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * @ignore
+ */
+declare const POINTER_ATTRIBUTES: readonly ["onpointerenter", "onpointerleave", "onpointerdown", "onpointerup", "onpointermove"];
+/**
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
+ * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
+ * what both need — the `entity` contract, registration with the owning application (which joins
+ * picked scene nodes back to elements by identity, never by name), and the pointer listener
+ * bookkeeping that lets the application lazily attach its canvas handlers.
+ */
+declare class EntityBaseElement extends AsyncElement {
+    protected _entity: Entity | null;
+    /**
+     * The application element this entity is registered with, cached at registration time so the
+     * entity can be unregistered even once this element has left the DOM.
+     */
+    protected _appElement: AppElement | null;
+    /**
+     * The pointer event listeners for the entity.
+     */
+    private _listeners;
+    /**
+     * The event types for which an inline `onpointer*` attribute is currently present.
+     */
+    private _inlineHandlerTypes;
+    /**
+     * The PlayCanvas entity instance. `null` until the element is ready, and again once the
+     * entity is gone — await {@link whenReady} or the element's `ready()` promise before
+     * accessing it.
+     * @returns The entity instance, or `null`.
+     */
+    get entity(): Entity | null;
+    /**
+     * Registers `entity` as this element's backing entity with the owning application, which
+     * joins engine nodes back to elements by identity (never by name).
+     *
+     * @param entity - The entity to register.
+     */
+    protected _registerEntity(entity: Entity): void;
+    /**
+     * Removes the registration for `entity`.
+     *
+     * @param entity - The entity to unregister.
+     */
+    protected _unregisterEntity(entity: Entity): void;
+    /**
+     * 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.
+     */
+    protected _updateInlineHandler(name: string, value: string | null): void;
+    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
+}
+export { EntityBaseElement, POINTER_ATTRIBUTES };

package/dist/entity.d.ts

@@ -1,5 +1,5 @@
-import { Entity, Vec3 } from 'playcanvas';
-import { AsyncElement } from './async-element';
+import { Vec3 } from 'playcanvas';
+import { EntityBaseElement } from './entity-base';
 /**
  * The EntityElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
@@ -24,7 +24,7 @@ import { AsyncElement } from './async-element';
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
  */
-declare class EntityElement extends AsyncElement {
+declare class EntityElement extends EntityBaseElement {
     /**
      * Whether the entity is enabled.
      */
@@ -49,31 +49,10 @@ declare class EntityElement extends AsyncElement {
      * The tags of the entity.
      */
     private _tags;
-    /**
-     * 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 application element this entity is registered with, cached at creation time so the
-     * entity can be unregistered even once this element has left the DOM.
-     */
-    private _appElement;
-    /**
-     * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
-     * been removed from the document — await {@link whenReady} or the element's `ready()`
-     * promise before accessing it.
-     * @returns The entity instance, or `null`.
-     */
-    get entity(): Entity | null;
     /**
      * Handles the destruction of the backing entity. Resets the element so a later re-insertion
      * starts clean: `_built` must be cleared alongside `_entity`, or _buildHierarchy would bail
@@ -146,21 +125,7 @@ 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 | null, newValue: string | null): void;
-    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
 }
 export { EntityElement };

package/dist/index.d.ts

@@ -31,8 +31,10 @@ import { ScriptElement } from './components/script';
 import { SoundComponentElement } from './components/sound-component';
 import { SoundSlotElement } from './components/sound-slot';
 import { GSplatComponentElement } from './components/gsplat-component';
+import { EntityBaseElement } from './entity-base';
 import { MaterialElement } from './material';
 import { ModelElement } from './model';
+import { NodeElement } from './node';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
 import type { ScriptAttributesChangeEvent, ScriptEnableChangeEvent, ScriptNameChangeEvent } from './components/script-component';
@@ -58,6 +60,7 @@ declare global {
         'pc-material': MaterialElement;
         'pc-model': ModelElement;
         'pc-module': ModuleElement;
+        'pc-node': NodeElement;
         'pc-particles': ParticleSystemComponentElement;
         'pc-render': RenderComponentElement;
         'pc-rigidbody': RigidBodyComponentElement;
@@ -72,5 +75,5 @@ declare global {
         'pc-sounds': SoundComponentElement;
     }
 }
-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 { 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, EntityBaseElement, MaterialElement, ModelElement, NodeElement, SceneElement, SkyElement, whenReady };
 export type { AsyncElementTagName } from './async-element';

package/dist/material.d.ts

@@ -160,7 +160,8 @@ declare class MaterialElement extends HTMLElement {
     private _setMap;
     /**
      * @param slot - The material property to write.
-     * @param texture - The loaded texture.
+     * @param texture - The loaded texture, applied with its sampler state untouched - anisotropy
+     * and friends belong to the `pc-asset`'s texture options.
      */
     private _applyMap;
     /**

package/dist/model.d.ts

@@ -5,6 +5,21 @@ import { AsyncElement } from './async-element';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
  * The ModelElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * The element becomes ready once its container asset has loaded and the instantiated hierarchy has
+ * been added to the scene — `entity` is non-null by then. A failed load also settles readiness,
+ * with `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen
+ * for `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness
+ * and instantiates anew, so a `ready()` obtained after the change resolves against the new
+ * hierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never
+ * becomes ready.
+ *
+ * @fires {Event} load - Fired each time a container asset finishes instantiating, including
+ * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor.
+ * @fires {ErrorEvent} error - Fired when the container asset fails to load, with the engine's
+ * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
+ * settled, not that it succeeded.
  */
 declare class ModelElement extends AsyncElement {
     private _asset;
@@ -17,11 +32,12 @@ declare class ModelElement extends AsyncElement {
      */
     private _loadGeneration;
     /**
-     * The pending asset-load subscription of the current load, if it is waiting for its asset.
-     * Held so that whatever supersedes the load can detach the handler from the asset, rather
-     * than leave it registered until the asset loads (or forever, if it never does).
+     * 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).
      */
     private _loadHandle;
+    private _errorHandle;
     /**
      * The root entity of the instantiated model. `null` until the container asset has loaded
      * and been instantiated, and again once the element has been removed from the document.
@@ -30,7 +46,13 @@ declare class ModelElement extends AsyncElement {
     get entity(): Entity | null;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private _detachLoadHandler;
+    private _detachLoadHandlers;
+    /**
+     * Resolves readiness and dispatches the `load` event. Called once the instantiated hierarchy
+     * has been parented — readiness means "in the scene graph", matching `pc-entity`, so a ready
+     * model's entity always has world transforms.
+     */
+    private _announceLoad;
     private _instantiate;
     private _loadModel;
     private _unloadModel;

package/dist/node.d.ts

@@ -0,0 +1,253 @@
+import { Vec3 } from 'playcanvas';
+import { EntityBaseElement } from './entity-base';
+/**
+ * The binding states a `<pc-node>` element moves through. `pending` while the host has not yet
+ * instantiated (or no `name` is assigned), `bound` once a node has been resolved and decorated,
+ * `missing`/`ambiguous`/`duplicate` when resolution failed — each accompanied by a warning
+ * naming the cause.
+ */
+type NodeBindingState = 'pending' | 'bound' | 'missing' | 'ambiguous' | 'duplicate';
+/**
+ * The NodeElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-node/ | `<pc-node>`}
+ * elements. The NodeElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * A `pc-node` is an override element: where `pc-entity` creates an entity, `pc-node` binds to a
+ * node a `pc-model` loaded and declares overrides against the authored asset — components to
+ * add, properties to change, content to attach. Attributes present apply as overrides; attributes
+ * absent leave authored values untouched, and removing an attribute (or assigning `null` to the
+ * matching property) restores the authored value.
+ *
+ * `name` selects among the host model's nodes (first match in depth-first order), nesting a
+ * `pc-node` inside another scopes the search to that subtree, and `index` picks among identically
+ * named matches. When `name` matches more than one node and no `index` is given, the element
+ * warns and binds nothing.
+ *
+ * The element becomes ready once bound, and never while unresolved — a missing or ambiguous
+ * name warns and records the failure in `state`, readiness stays unresolved, and descendants
+ * wait with it.
+ *
+ * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
+ * intersects the bound node's geometry, exactly as for `<pc-entity>`.
+ *
+ * @attribute {string} name - The name of the node to bind, resolved within the nearest ancestor
+ * `pc-model` (or `pc-node`) once it has instantiated.
+ * @attribute {number} index - Which match to bind when `name` matches more than one node,
+ * 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.
+ * @attribute {boolean} enabled - Overrides the node's enabled state.
+ * @attribute {string} position - Overrides the node's local position, as an "x y z" triple.
+ * @attribute {string} rotation - Overrides the node's local rotation (Euler angles), as an
+ * "x y z" triple.
+ * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
+ * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+ * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
+ * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
+ * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
+ * @attribute {string} onpointerdown - Script to run when a pointer button is pressed over the
+ * node.
+ * @attribute {string} onpointerup - Script to run when a pointer button is released over the
+ * node.
+ * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
+ * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
+ * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
+ * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
+ * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+ */
+declare class NodeElement extends EntityBaseElement {
+    private _name;
+    private _index;
+    private _state;
+    private _path;
+    /**
+     * The element whose entity roots this element's search: the nearest ancestor `pc-node`, or
+     * failing that the nearest ancestor `pc-model`. Resolved on connection.
+     */
+    private _host;
+    /**
+     * The listener following the host's binding cycles. Both host kinds announce each cycle
+     * with a `ready` event — `pc-model` on every instantiation, `pc-node` on every bind.
+     */
+    private _hostListener;
+    /**
+     * The subscription to the bound entity's destruction, detached on unbind so a retargeted
+     * element cannot be reset by the eventual death of a node it no longer fronts.
+     */
+    private _destroyHandle;
+    /** The authored values displaced by this element's overrides, captured per property. */
+    private _authored;
+    private _enabled;
+    private _position;
+    private _rotation;
+    private _scale;
+    private _tags;
+    /**
+     * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
+     * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
+     * warns). Useful for asserting a document's bindings programmatically.
+     * @returns The binding state.
+     */
+    get state(): NodeBindingState;
+    /**
+     * The path of the bound node below the search root, `/`-separated, or `null` while not
+     * bound.
+     * @returns The bound node's path, or `null`.
+     */
+    get path(): string | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Re-resolves the binding against the host's current hierarchy: on connection, on a `name`
+     * or `index` change, and on every host cycle (a model [re]instantiating, an enclosing
+     * `pc-node` [re]binding). When re-resolution yields the entity already bound, the binding
+     * is retained untouched — a redundant edit must not flicker overrides through a revert.
+     */
+    private _rebind;
+    /**
+     * Resolves `name` (and `index`) to an entity under `hostEntity`, warning and recording the
+     * failure state when it cannot.
+     *
+     * @param hostEntity - The root of the search.
+     * @returns The resolved entity, or `null`.
+     */
+    private _resolve;
+    /**
+     * Binds `target`: registers it (making it a pick target), hooks its destruction, applies
+     * this element's overrides, announces readiness and builds the deferred child subtree.
+     *
+     * @param target - The entity to bind.
+     * @param hostEntity - The search root, for the path.
+     */
+    private _bind;
+    /**
+     * Dissolves the current binding, restoring every authored value this element's overrides
+     * displaced and removing the decorations this binding hosts: attachment entities are
+     * destroyed (re-created against the next binding) and component decorations are removed
+     * from the abandoned node. Both sweeps are scoped by `closestEntity`, so a still-bound
+     * nested `pc-node` keeps its own decorations. Safe to call in any state.
+     */
+    private _unbind;
+    /**
+     * Handles the destruction of the bound entity - its model unloading, reloading, or a script
+     * destroying it. There is nothing to revert on a destroyed entity; the element returns to
+     * pending and the host's next cycle re-resolves it.
+     */
+    private _onEntityDestroy;
+    /**
+     * Creates and parents the entities of child `pc-entity` elements - the attachment points.
+     * Mirrors the runtime-insertion path in EntityElement.connectedCallback: children were
+     * deferred while this host was unresolved (or reset when a previous binding dissolved), and
+     * build here once it binds.
+     */
+    private _buildChildren;
+    /**
+     * Applies every override that is explicitly set, capturing the authored value it displaces.
+     */
+    private _applyOverrides;
+    /**
+     * Restores every authored value this element's overrides displaced. The override values
+     * themselves are kept - they re-apply on the next binding.
+     */
+    private _revertOverrides;
+    /**
+     * Renders the path of `node` below `root`, for the `path` property and the resolution
+     * warnings.
+     *
+     * @param node - The node to describe.
+     * @param root - The search root.
+     * @returns The `/`-separated path.
+     */
+    private _pathOf;
+    /**
+     * Describes the search root for warnings: the model's asset id, or the enclosing node's
+     * name.
+     * @returns The description.
+     */
+    private _describeHost;
+    /**
+     * Finds the node name nearest to the missing `name`, for the miss warning. The names are
+     * already in hand from resolution, so the suggestion is nearly free.
+     *
+     * @param hostEntity - The root of the search.
+     * @returns The closest name within an edit distance of 2, or `null`.
+     */
+    private _closestName;
+    /**
+     * Sets the name of the node to bind. A change retargets: the current binding's overrides
+     * revert and the new name resolves afresh. `name` on a `pc-node` is never a rename of the
+     * authored node - it is only ever a reference.
+     * @param value - The node name.
+     */
+    set name(value: string);
+    /**
+     * Gets the name of the node to bind.
+     * @returns The node name.
+     */
+    get name(): string;
+    /**
+     * Sets which match to bind when `name` matches more than one node, 0-based in depth-first
+     * order. A change retargets, like `name`. `null` means unset - required when the name is
+     * ambiguous, optional otherwise.
+     * @param value - The match index, or `null`.
+     */
+    set index(value: number | null);
+    /**
+     * Gets which match to bind.
+     * @returns The match index, or `null` when unset.
+     */
+    get index(): number | null;
+    /**
+     * Sets the enabled override. `null` clears it, restoring the authored state.
+     * @param value - The enabled state, or `null`.
+     */
+    set enabled(value: boolean | null);
+    /**
+     * Gets the enabled override.
+     * @returns The enabled state, or `null` while no override is set.
+     */
+    get enabled(): boolean | null;
+    /**
+     * Sets the local position override. `null` clears it, restoring the authored position.
+     * @param value - The position, or `null`.
+     */
+    set position(value: Vec3 | null);
+    /**
+     * Gets the local position override.
+     * @returns The position, or `null` while no override is set.
+     */
+    get position(): Vec3 | null;
+    /**
+     * Sets the local rotation override, as Euler angles in degrees. `null` clears it, restoring
+     * the authored rotation.
+     * @param value - The rotation, or `null`.
+     */
+    set rotation(value: Vec3 | null);
+    /**
+     * Gets the local rotation override.
+     * @returns The rotation, or `null` while no override is set.
+     */
+    get rotation(): Vec3 | null;
+    /**
+     * Sets the local scale override. `null` clears it, restoring the authored scale.
+     * @param value - The scale, or `null`.
+     */
+    set scale(value: Vec3 | null);
+    /**
+     * Gets the local scale override.
+     * @returns The scale, or `null` while no override is set.
+     */
+    get scale(): Vec3 | null;
+    /**
+     * Sets the tags override. `null` clears it, restoring the authored tags.
+     * @param value - The tags, or `null`.
+     */
+    set tags(value: string[] | null);
+    /**
+     * Gets the tags override.
+     * @returns The tags, or `null` while no override is set.
+     */
+    get tags(): string[] | null;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { NodeElement };