@playcanvas/web-components 0.11.1 → 0.13.0

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.cts

@@ -0,0 +1,72 @@
+import type { Entity } from 'playcanvas';
+import { AsyncElement } from './async-element.cjs';
+/**
+ * The ModelElement interface provides properties and methods for manipulating
+ * {@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;
+    private _entity;
+    /**
+     * Incremented on every new load and on disconnect, 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 entity nor parent one that has
+     * since been destroyed.
+     */
+    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).
+     */
+    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.
+     * @returns The model's root entity, or `null`.
+     */
+    get entity(): Entity | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    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;
+    /**
+     * Sets the id of the `pc-asset` to use for the model.
+     * @param value - The asset ID.
+     */
+    set asset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the model.
+     * @returns The asset ID.
+     */
+    get asset(): string;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { ModelElement };

package/dist/model.d.ts

@@ -1,10 +1,25 @@
 import type { Entity } from 'playcanvas';
-import { AsyncElement } from './async-element';
+import { AsyncElement } from './async-element.js';
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@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/module.d.cts

@@ -0,0 +1,29 @@
+import { AsyncElement } from './async-element.cjs';
+/**
+ * The ModuleElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+ * elements. The ModuleElement interface also inherits the properties and methods of the
+ * {@link AsyncElement} interface.
+ *
+ * The attributes are read once, when the module starts loading - on the element's first
+ * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+ * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+ * modules configure engine-global state that never unloads, so readiness is not re-armed by
+ * removing the element, and a re-inserted element does not load again.
+ *
+ * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * boots.
+ *
+ * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
+ * `Ammo`.
+ * @attribute {string} glue - The URL of the module's glue script.
+ * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+ * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+ * WebAssembly is unavailable.
+ */
+declare class ModuleElement extends AsyncElement {
+    private _loadPromise;
+    connectedCallback(): void;
+    private _loadModule;
+}
+export { ModuleElement };

package/dist/module.d.ts

@@ -1,11 +1,18 @@
+import { AsyncElement } from './async-element.js';
 /**
  * The ModuleElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
- * The ModuleElement interface also inherits the properties and methods of the
- * {@link HTMLElement} interface.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+ * elements. The ModuleElement interface also inherits the properties and methods of the
+ * {@link AsyncElement} interface.
  *
- * Note that these attributes are read once when the element is created, so changing them later
- * has no effect.
+ * The attributes are read once, when the module starts loading - on the element's first
+ * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+ * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+ * modules configure engine-global state that never unloads, so readiness is not re-armed by
+ * removing the element, and a re-inserted element does not load again.
+ *
+ * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * boots.
  *
  * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
  * `Ammo`.
@@ -14,10 +21,9 @@
  * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
  * WebAssembly is unavailable.
  */
-declare class ModuleElement extends HTMLElement {
-    private loadPromise;
-    /** @ignore */
-    constructor();
-    private loadModule;
+declare class ModuleElement extends AsyncElement {
+    private _loadPromise;
+    connectedCallback(): void;
+    private _loadModule;
 }
 export { ModuleElement };

package/dist/node.d.cts

@@ -0,0 +1,253 @@
+import { Vec3 } from 'playcanvas';
+import { EntityBaseElement } from './entity-base.cjs';
+/**
+ * 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 };