@playcanvas/web-components 0.15.0 → 0.17.0

package/dist/app.d.cts

@@ -53,9 +53,9 @@ declare class AppElement extends AsyncElement {
     private _bootGeneration;
     /**
      * The elements backing this application's entities, keyed by the entity itself. Registered
-     * by EntityElement at creation (and NodeElement at binding) and removed when an entity is
-     * destroyed or unbound, this joins engine scene nodes back to their owning elements by
-     * identity - never by name.
+     * by entity-owning elements at creation (pc-entity, and pc-model for its host) and by
+     * NodeElement at binding, and removed when an entity is destroyed or unbound, this joins
+     * engine scene nodes back to their owning elements by identity - never by name.
      */
     private _entityElements;
     private _picker;
@@ -103,25 +103,26 @@ declare class AppElement extends AsyncElement {
     private _pickerCreate;
     private _pickerDestroy;
     /**
-     * Returns the `<pc-entity>` or `<pc-node>` element whose backing entity is `entity`, or
-     * `null` if the entity is not fronted by an element of this application - for example, an
-     * unbound node inside a model's instantiated hierarchy, or an entity created through the
-     * engine API.
+     * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
+     * `entity`, or `null` if the entity is not fronted by an element of this application - for
+     * example, an unbound node inside a model's instantiated hierarchy, or an entity created
+     * through the engine API.
      *
      * @param entity - The entity to look up.
      * @returns The element fronting the entity, or `null`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | null;
     /**
-     * Resolves the element that owns a picked node: the nearest node up the parent chain -
-     * starting with the node itself - that is fronted by a `<pc-entity>` or `<pc-node>` of this
-     * application. A hit inside a model's instantiated hierarchy therefore resolves to the
-     * nearest bound `<pc-node>`, or failing that the element hosting the model.
+     * Resolves the element that owns hover for a picked node: the nearest node up the parent
+     * chain - starting with the node itself - whose element listens for any of the hover event
+     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
+     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
+     * to hover rather than swallowing a listening ancestor's enter/leave pair.
      *
      * @param node - The picked node, or `null`.
-     * @returns The owning element, or `null`.
+     * @returns The hover-owning element, or `null`.
      */
-    private _elementFromNode;
+    private _hoverTarget;
     /**
      * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
      * on an unlistened child still reaches a listening ancestor.

package/dist/app.d.ts

@@ -53,9 +53,9 @@ declare class AppElement extends AsyncElement {
     private _bootGeneration;
     /**
      * The elements backing this application's entities, keyed by the entity itself. Registered
-     * by EntityElement at creation (and NodeElement at binding) and removed when an entity is
-     * destroyed or unbound, this joins engine scene nodes back to their owning elements by
-     * identity - never by name.
+     * by entity-owning elements at creation (pc-entity, and pc-model for its host) and by
+     * NodeElement at binding, and removed when an entity is destroyed or unbound, this joins
+     * engine scene nodes back to their owning elements by identity - never by name.
      */
     private _entityElements;
     private _picker;
@@ -103,25 +103,26 @@ declare class AppElement extends AsyncElement {
     private _pickerCreate;
     private _pickerDestroy;
     /**
-     * Returns the `<pc-entity>` or `<pc-node>` element whose backing entity is `entity`, or
-     * `null` if the entity is not fronted by an element of this application - for example, an
-     * unbound node inside a model's instantiated hierarchy, or an entity created through the
-     * engine API.
+     * Returns the `<pc-entity>`, `<pc-model>` or `<pc-node>` element whose backing entity is
+     * `entity`, or `null` if the entity is not fronted by an element of this application - for
+     * example, an unbound node inside a model's instantiated hierarchy, or an entity created
+     * through the engine API.
      *
      * @param entity - The entity to look up.
      * @returns The element fronting the entity, or `null`.
      */
     elementFromEntity(entity: Entity): EntityBaseElement | null;
     /**
-     * Resolves the element that owns a picked node: the nearest node up the parent chain -
-     * starting with the node itself - that is fronted by a `<pc-entity>` or `<pc-node>` of this
-     * application. A hit inside a model's instantiated hierarchy therefore resolves to the
-     * nearest bound `<pc-node>`, or failing that the element hosting the model.
+     * Resolves the element that owns hover for a picked node: the nearest node up the parent
+     * chain - starting with the node itself - whose element listens for any of the hover event
+     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
+     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
+     * to hover rather than swallowing a listening ancestor's enter/leave pair.
      *
      * @param node - The picked node, or `null`.
-     * @returns The owning element, or `null`.
+     * @returns The hover-owning element, or `null`.
      */
-    private _elementFromNode;
+    private _hoverTarget;
     /**
      * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
      * on an unlistened child still reaches a listening ancestor.

package/dist/async-element.d.cts

@@ -20,9 +20,9 @@ declare class AsyncElement extends HTMLElement {
      */
     get closestApp(): AppElement | null;
     /**
-     * The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or
-     * `null` if this element has no such ancestor. The search starts at the parent, so an element
-     * never resolves to itself.
+     * The nearest ancestor element that fronts an entity — `<pc-entity>`, `<pc-model>` or
+     * `<pc-node>` — or `null` if this element has no such ancestor. The search starts at the
+     * parent, so an element never resolves to itself.
      * @returns The closest entity-fronting element, or `null`.
      */
     get closestEntity(): EntityBaseElement | null;
@@ -62,11 +62,11 @@ type AsyncElementTagName = {
 }[keyof HTMLElementTagNameMap];
 /**
  * Waits for the first element matching the given tag name to be fully initialized. Note that the
- * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example
@@ -87,11 +87,11 @@ declare function whenReady<K extends AsyncElementTagName>(target: K): Promise<HT
 declare function whenReady<T extends AsyncElement>(target: T): Promise<T>;
 /**
  * Waits for the first element matching the given CSS selector to be fully initialized. Note that
- * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * the promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example

package/dist/async-element.d.ts

@@ -20,9 +20,9 @@ declare class AsyncElement extends HTMLElement {
      */
     get closestApp(): AppElement | null;
     /**
-     * The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or
-     * `null` if this element has no such ancestor. The search starts at the parent, so an element
-     * never resolves to itself.
+     * The nearest ancestor element that fronts an entity — `<pc-entity>`, `<pc-model>` or
+     * `<pc-node>` — or `null` if this element has no such ancestor. The search starts at the
+     * parent, so an element never resolves to itself.
      * @returns The closest entity-fronting element, or `null`.
      */
     get closestEntity(): EntityBaseElement | null;
@@ -62,11 +62,11 @@ type AsyncElementTagName = {
 }[keyof HTMLElementTagNameMap];
 /**
  * Waits for the first element matching the given tag name to be fully initialized. Note that the
- * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example
@@ -87,11 +87,11 @@ declare function whenReady<K extends AsyncElementTagName>(target: K): Promise<HT
 declare function whenReady<T extends AsyncElement>(target: T): Promise<T>;
 /**
  * Waits for the first element matching the given CSS selector to be fully initialized. Note that
- * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
- * that is not a direct child of `<pc-scripts>`, or a `<pc-app>` that could not create a graphics
- * device — listen for its `error` event instead). A component element outside a `<pc-entity>` is
- * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
- * element logs a warning naming the parent it requires.
+ * the promise never settles if the element cannot finish initializing (for example, a `<pc-script-instance>`
+ * that is not a direct child of `<pc-script>`, or a `<pc-app>` that could not create a graphics
+ * device — listen for its `error` event instead). A component element outside an entity-fronting
+ * element is the exception: it still becomes ready, but its `component` is `null`. Either way, a
+ * misplaced element logs a warning naming the parent it requires.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).
  * @returns A promise that resolves with the element once it's ready.
  * @example

package/dist/components/anim-clip.d.cts

@@ -0,0 +1,127 @@
+import { AsyncElement } from '../async-element.cjs';
+import { AnimComponentElement } from './anim-component.cjs';
+/**
+ * The AnimClipElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/ | `<pc-anim-clip>`}
+ * elements. The AnimClipElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * A clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name
+ * and the track looked up in the clip's source: an explicit `asset` (a `container`, an
+ * `animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`
+ * enclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is
+ * named; in a multi-track source the track named `name` is chosen, falling back to the first
+ * with a warning. The element becomes ready once its resolved track is assigned.
+ *
+ * @category Components
+ */
+declare class AnimClipElement extends AsyncElement {
+    /**
+     * The `<pc-anim>` this clip was adopted by, captured when the parent adopts the clip and on
+     * connection.
+     *
+     * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+     * `parentElement` is already `null`, so a lookup would both fail to find the component and
+     * emit a misleading "must be a direct child" warning for what is an ordinary removal.
+     */
+    private _animElement;
+    private _asset;
+    /**
+     * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
+     * a resume from an await abandons itself if the value has moved on, so a stale callback can
+     * neither act on a torn-down tree nor register its clip alongside a re-inserted element's
+     * own callback.
+     */
+    private _connectionGeneration;
+    private _errorHandle;
+    /**
+     * Incremented on every track resolution and on disconnect, and captured by a resolution when
+     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
+     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     */
+    private _loadGeneration;
+    /**
+     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
+     * Held so that whatever supersedes the resolution 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 _loop;
+    private _name;
+    private _speed;
+    /**
+     * The source complaint already made — the asset id it was made for, or `''` for the
+     * no-asset-no-model case — so re-resolutions (host cycles, model reloads) do not repeat it.
+     */
+    private _warnedSource;
+    /**
+     * Whether the owning `<pc-anim>` already rejected this clip's name — its sweeps re-run on
+     * host cycles and must not repeat the complaint.
+     */
+    private _warnedInvalid;
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    protected get animElement(): AnimComponentElement | null;
+    private _detachLoadHandlers;
+    /**
+     * Complains about the clip's source, once per source value — resolutions re-run on host
+     * cycles and model reloads, and must not repeat the complaint.
+     */
+    private _warnSource;
+    /**
+     * Picks the clip's track out of a loaded source asset: the track named `name`, or a lone
+     * track whatever it is named, or the first of several with a warning.
+     *
+     * @param asset - The loaded source asset.
+     * @param source - How warnings name the source.
+     */
+    private _extractTrack;
+    /**
+     * Sets the id of the `pc-asset` supplying the clip's track: a `container`, an `animation`
+     * `.glb`, or an `animclip` JSON. When empty, the track comes from the container of the
+     * `<pc-model>` enclosing the parent `<pc-anim>`.
+     * @param value - The asset id.
+     */
+    set asset(value: string);
+    /**
+     * Gets the id of the `pc-asset` supplying the clip's track.
+     * @returns The asset id.
+     */
+    get asset(): string;
+    /**
+     * Sets whether the clip loops. A non-looping clip holds its last pose when it ends — the
+     * engine reports no completion. Defaults to `true`.
+     * @param value - Whether the clip loops.
+     */
+    set loop(value: boolean);
+    /**
+     * Gets whether the clip loops.
+     * @returns Whether the clip loops.
+     */
+    get loop(): boolean;
+    /**
+     * Sets the name of the clip: the name it is played by, and the track looked up in the
+     * clip's source. Names must be unique within a `<pc-anim>` and must not contain `.`.
+     * @param value - The clip name.
+     */
+    set name(value: string);
+    /**
+     * Gets the name of the clip.
+     * @returns The clip name.
+     */
+    get name(): string;
+    /**
+     * Sets the playback speed of the clip, where negative values play it backwards. Applies
+     * immediately, preserving the playhead. Defaults to 1.
+     * @param value - The playback speed.
+     */
+    set speed(value: number);
+    /**
+     * Gets the playback speed of the clip.
+     * @returns The playback speed.
+     */
+    get speed(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AnimClipElement };

package/dist/components/anim-clip.d.ts

@@ -0,0 +1,127 @@
+import { AsyncElement } from '../async-element.js';
+import { AnimComponentElement } from './anim-component.js';
+/**
+ * The AnimClipElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-anim-clip/ | `<pc-anim-clip>`}
+ * elements. The AnimClipElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * A clip declares one named animation on its parent `<pc-anim>`. `name` is both the clip's name
+ * and the track looked up in the clip's source: an explicit `asset` (a `container`, an
+ * `animation` `.glb`, or an `animclip` JSON), or, without one, the container of the `<pc-model>`
+ * enclosing the parent `<pc-anim>`. A source holding a single track supplies it whatever it is
+ * named; in a multi-track source the track named `name` is chosen, falling back to the first
+ * with a warning. The element becomes ready once its resolved track is assigned.
+ *
+ * @category Components
+ */
+declare class AnimClipElement extends AsyncElement {
+    /**
+     * The `<pc-anim>` this clip was adopted by, captured when the parent adopts the clip and on
+     * connection.
+     *
+     * `disconnectedCallback` cannot rediscover it: by the time the element is disconnected its
+     * `parentElement` is already `null`, so a lookup would both fail to find the component and
+     * emit a misleading "must be a direct child" warning for what is an ordinary removal.
+     */
+    private _animElement;
+    private _asset;
+    /**
+     * Incremented on every connect and disconnect, and captured by connectedCallback on entry —
+     * a resume from an await abandons itself if the value has moved on, so a stale callback can
+     * neither act on a torn-down tree nor register its clip alongside a re-inserted element's
+     * own callback.
+     */
+    private _connectionGeneration;
+    private _errorHandle;
+    /**
+     * Incremented on every track resolution and on disconnect, and captured by a resolution when
+     * it starts. A resolution that resumes from an await or an asset callback abandons itself if
+     * the value has moved on, so a superseded resolution cannot hand a stale track to the parent.
+     */
+    private _loadGeneration;
+    /**
+     * The pending asset subscriptions of the current resolution, if it is waiting for its asset.
+     * Held so that whatever supersedes the resolution 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 _loop;
+    private _name;
+    private _speed;
+    /**
+     * The source complaint already made — the asset id it was made for, or `''` for the
+     * no-asset-no-model case — so re-resolutions (host cycles, model reloads) do not repeat it.
+     */
+    private _warnedSource;
+    /**
+     * Whether the owning `<pc-anim>` already rejected this clip's name — its sweeps re-run on
+     * host cycles and must not repeat the complaint.
+     */
+    private _warnedInvalid;
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    protected get animElement(): AnimComponentElement | null;
+    private _detachLoadHandlers;
+    /**
+     * Complains about the clip's source, once per source value — resolutions re-run on host
+     * cycles and model reloads, and must not repeat the complaint.
+     */
+    private _warnSource;
+    /**
+     * Picks the clip's track out of a loaded source asset: the track named `name`, or a lone
+     * track whatever it is named, or the first of several with a warning.
+     *
+     * @param asset - The loaded source asset.
+     * @param source - How warnings name the source.
+     */
+    private _extractTrack;
+    /**
+     * Sets the id of the `pc-asset` supplying the clip's track: a `container`, an `animation`
+     * `.glb`, or an `animclip` JSON. When empty, the track comes from the container of the
+     * `<pc-model>` enclosing the parent `<pc-anim>`.
+     * @param value - The asset id.
+     */
+    set asset(value: string);
+    /**
+     * Gets the id of the `pc-asset` supplying the clip's track.
+     * @returns The asset id.
+     */
+    get asset(): string;
+    /**
+     * Sets whether the clip loops. A non-looping clip holds its last pose when it ends — the
+     * engine reports no completion. Defaults to `true`.
+     * @param value - Whether the clip loops.
+     */
+    set loop(value: boolean);
+    /**
+     * Gets whether the clip loops.
+     * @returns Whether the clip loops.
+     */
+    get loop(): boolean;
+    /**
+     * Sets the name of the clip: the name it is played by, and the track looked up in the
+     * clip's source. Names must be unique within a `<pc-anim>` and must not contain `.`.
+     * @param value - The clip name.
+     */
+    set name(value: string);
+    /**
+     * Gets the name of the clip.
+     * @returns The clip name.
+     */
+    get name(): string;
+    /**
+     * Sets the playback speed of the clip, where negative values play it backwards. Applies
+     * immediately, preserving the playhead. Defaults to 1.
+     * @param value - The playback speed.
+     */
+    set speed(value: number);
+    /**
+     * Gets the playback speed of the clip.
+     * @returns The playback speed.
+     */
+    get speed(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AnimClipElement };