@playcanvas/web-components 0.11.1 → 0.13.0

package/dist/asset.d.ts

@@ -1,5 +1,8 @@
 import { Asset } from 'playcanvas';
-import { AsyncElement } from './async-element';
+import { AsyncElement } from './async-element.js';
+type AddressMode = 'repeat' | 'clamp' | 'mirror';
+type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+type MagFilterMode = 'nearest' | 'linear';
 /**
  * The AssetElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
@@ -13,8 +16,16 @@ import { AsyncElement } from './async-element';
  * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
  * elsewhere, or with an unsupported asset type, never become ready.
  *
- * Apart from `lazy`, these attributes are read once when the asset is created, so changing them
- * later has no effect.
+ * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
+ * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
+ * created and — like `lazy` — are observed: changing one updates a texture that has already
+ * loaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded
+ * texture recreates the underlying GPU resource, so prefer declaring those up front. Each option
+ * overrides the matching key in the `data` JSON; options left unset write nothing, leaving the
+ * engine's per-format defaults in force.
+ *
+ * Apart from `lazy` and the texture options, these attributes are read once when the asset is
+ * created, so changing them later has no effect.
  *
  * @attribute {string} id - The identifier used to reference the asset from other elements.
  * @attribute {string} src - The URL of the asset to load.
@@ -36,7 +47,15 @@ import { AsyncElement } from './async-element';
  * not that it succeeded.
  */
 declare class AssetElement extends AsyncElement {
+    private _addressU;
+    private _addressV;
+    private _anisotropy;
+    private _flipY;
     private _lazy;
+    private _magFilter;
+    private _minFilter;
+    private _mipmaps;
+    private _srgb;
     /**
      * The asset that is loaded. Available once the element is ready — await
      * {@link whenReady} or the element's `ready()` promise before accessing it.
@@ -47,14 +66,85 @@ declare class AssetElement extends AsyncElement {
     private _onAssetLoad;
     private _onAssetError;
     /**
-     * Builds the `data` object for the asset from an optional inline `data` attribute (JSON) and,
-     * for sprites, from the convenience attributes (`atlas`, `frame-keys`, `pixels-per-unit`,
-     * `render-mode`). Returns `undefined` when there is no data to apply.
+     * Builds the `data` object for the asset from an optional inline `data` attribute (JSON), the
+     * texture option attributes (for `texture` and `textureatlas` assets), and the sprite
+     * convenience attributes (`atlas`, `frame-keys`, `pixels-per-unit`, `render-mode`). An
+     * attribute overrides the matching `data` JSON key. Returns `undefined` when there is no data
+     * to apply.
      * @param type - The resolved asset type.
      * @returns The asset data, or `undefined`.
      */
     private _buildData;
+    /**
+     * Returns the engine texture behind this asset, when there is one: the resource itself for a
+     * `texture` asset, the atlas's texture for a `textureatlas` asset, `null` otherwise
+     * (including before the asset has loaded).
+     * @returns The texture, or `null`.
+     */
+    private _texture;
+    /**
+     * Writes one texture option through to the created asset, if any. The engine-JSON key is
+     * written into `asset.data`, mutated in place - replacing the whole object would make the
+     * registry re-patch every key, and a re-patched `srgb` or `mipmaps` recreates the texture
+     * even when unchanged. The in-place key is what a not-yet-started load reads at texture
+     * construction, and what any later reload reads. When the texture already exists, the
+     * corresponding property is assigned directly; `null` (attribute removed) deletes the key
+     * and restores the engine default. Assets of any other type are left untouched.
+     *
+     * @param key - The engine texture JSON key in `asset.data`.
+     * @param property - The Texture property to assign.
+     * @param dataValue - The engine-JSON value for `asset.data`, or `null` to delete the key.
+     * @param textureValue - The value for the Texture property, or `null` for the engine default.
+     */
+    private _applyTextureOption;
     private _destroyAsset;
+    /**
+     * Sets the texture's horizontal (U) address mode: how texture coordinates outside the 0 to 1
+     * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+     * texture is created and after it has loaded.
+     * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+     */
+    set addressU(value: AddressMode | null);
+    /**
+     * Gets the texture's horizontal (U) address mode.
+     * @returns The address mode, or `null` when unset.
+     */
+    get addressU(): AddressMode | null;
+    /**
+     * Sets the texture's vertical (V) address mode: how texture coordinates outside the 0 to 1
+     * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+     * texture is created and after it has loaded.
+     * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+     */
+    set addressV(value: AddressMode | null);
+    /**
+     * Gets the texture's vertical (V) address mode.
+     * @returns The address mode, or `null` when unset.
+     */
+    get addressV(): AddressMode | null;
+    /**
+     * Sets the texture's maximum anisotropic filtering level, which improves quality at oblique
+     * viewing angles. Applies to `texture` and `textureatlas` assets, both when the texture is
+     * created and after it has loaded.
+     * @param value - The anisotropy level, or `null` to use the engine default of 1.
+     */
+    set anisotropy(value: number | null);
+    /**
+     * Gets the texture's maximum anisotropic filtering level.
+     * @returns The anisotropy level, or `null` when unset.
+     */
+    get anisotropy(): number | null;
+    /**
+     * Sets whether the texture's image data is flipped vertically at upload. Applies to `texture`
+     * and `textureatlas` assets, both when the texture is created and after it has loaded.
+     * @param value - The flip flag, or `null` to use the engine default of `false`.
+     */
+    set flipY(value: boolean | null);
+    /**
+     * Gets whether the texture's image data is flipped vertically at upload.
+     * @returns The flip flag, or `null` when unset.
+     */
+    get flipY(): boolean | null;
     /**
      * Sets whether the asset should be loaded lazily.
      * @param value - The lazy loading flag.
@@ -65,6 +155,55 @@ declare class AssetElement extends AsyncElement {
      * @returns The lazy loading flag.
      */
     get lazy(): boolean;
+    /**
+     * Sets the texture's magnification filter, used when the texture is displayed larger than its
+     * source size. Applies to `texture` and `textureatlas` assets, both when the texture is
+     * created and after it has loaded.
+     * @param value - The filter, or `null` to use the engine default of 'linear'.
+     */
+    set magFilter(value: MagFilterMode | null);
+    /**
+     * Gets the texture's magnification filter.
+     * @returns The filter, or `null` when unset.
+     */
+    get magFilter(): MagFilterMode | null;
+    /**
+     * Sets the texture's minification filter, used when the texture is displayed smaller than its
+     * source size. The mip variants blend within (and, for the second `linear`, between) mipmap
+     * levels. Applies to `texture` and `textureatlas` assets, both when the texture is created
+     * and after it has loaded.
+     * @param value - The filter, or `null` to use the engine default of 'linear-mip-linear'.
+     */
+    set minFilter(value: MinFilterMode | null);
+    /**
+     * Gets the texture's minification filter.
+     * @returns The filter, or `null` when unset.
+     */
+    get minFilter(): MinFilterMode | null;
+    /**
+     * Sets whether the texture generates and uses mipmaps. Changing this on a loaded texture
+     * recreates the underlying GPU resource, so prefer declaring it up front. Applies to
+     * `texture` and `textureatlas` assets.
+     * @param value - The mipmaps flag, or `null` to use the engine default of `true`.
+     */
+    set mipmaps(value: boolean | null);
+    /**
+     * Gets whether the texture generates and uses mipmaps.
+     * @returns The mipmaps flag, or `null` when unset.
+     */
+    get mipmaps(): boolean | null;
+    /**
+     * Sets whether the texture holds sRGB (gamma-encoded) color data, enabling hardware gamma
+     * decode. Free when set before the texture loads; changing it on a loaded texture recreates
+     * the underlying GPU resource. Applies to `texture` and `textureatlas` assets.
+     * @param value - The sRGB flag, or `null` to use the engine default of `false`.
+     */
+    set srgb(value: boolean | null);
+    /**
+     * Gets whether the texture holds sRGB (gamma-encoded) color data.
+     * @returns The sRGB flag, or `null` when unset.
+     */
+    get srgb(): boolean | null;
     /**
      * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
      * `undefined` if there is no such element or its asset has not been created yet.

package/dist/async-element.d.cts

@@ -0,0 +1,103 @@
+import type { AppElement } from './app.cjs';
+import type { EntityBaseElement } from './entity-base.cjs';
+/**
+ * Base class for all PlayCanvas Web Components that initialize asynchronously.
+ *
+ * @fires {CustomEvent} ready - Fired when the element is fully initialized — once per readiness
+ * cycle, so an element that is torn down and re-initialized (for example by removing and
+ * re-inserting it) fires it again. Bubbles and is composed.
+ */
+declare class AsyncElement extends HTMLElement {
+    private _readyPromise;
+    private _readyResolve;
+    private _readyResolved;
+    /** @ignore */
+    constructor();
+    /**
+     * The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest app element, or `null`.
+     */
+    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.
+     * @returns The closest entity-fronting element, or `null`.
+     */
+    get closestEntity(): EntityBaseElement | null;
+    /**
+     * Called when the element is fully initialized and ready. Subclasses should call this when
+     * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
+     * event. Signals at most once per readiness cycle: a repeat call before {@link _resetReady}
+     * has re-armed the promise does nothing.
+     */
+    protected _onReady(): void;
+    /**
+     * Returns the ready promise to its pending state. Subclasses should call this when the
+     * resource their readiness announced is torn down (typically from `disconnectedCallback`),
+     * so that a later re-initialization can signal readiness again. Does nothing while the
+     * promise is still pending — an in-flight waiter carries over to the next readiness cycle
+     * rather than being stranded on a promise nothing will ever resolve.
+     */
+    protected _resetReady(): void;
+    /**
+     * Returns a promise that resolves with this element when it's ready. This is the low-level
+     * primitive underlying {@link whenReady}, which is the recommended way to wait for elements.
+     *
+     * Readiness tracks the element's current lifecycle: once a ready element is torn down (for
+     * example by removing it from the document), this returns a fresh promise that resolves when
+     * the element is next ready. A promise obtained earlier stays resolved — call this again
+     * after re-inserting an element rather than reusing a promise from before its removal.
+     * @returns A promise that resolves with this element when it's ready.
+     */
+    ready(): Promise<this>;
+}
+/**
+ * A union of the tag names of all elements that initialize asynchronously (i.e. elements whose
+ * classes extend {@link AsyncElement}).
+ */
+type AsyncElementTagName = {
+    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never;
+}[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.
+ * @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
+ * const { app } = await whenReady('pc-app');
+ */
+declare function whenReady<K extends AsyncElementTagName>(target: K): Promise<HTMLElementTagNameMap[K]>;
+/**
+ * Waits for the given element to be fully initialized. Note that the promise never settles if
+ * the element cannot finish initializing (for example, an element that is never added to the
+ * document).
+ * @param target - The element to wait for.
+ * @returns A promise that resolves with the element once it's ready.
+ * @example
+ * const appElement = document.createElement('pc-app');
+ * document.body.appendChild(appElement);
+ * const { app } = await whenReady(appElement);
+ */
+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.
+ * @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
+ * // In TypeScript, supply the element type when using an arbitrary selector
+ * const { entity } = await whenReady<EntityElement>('pc-entity[name="camera"]');
+ */
+declare function whenReady<T extends AsyncElement = AsyncElement, S extends string = string>(target: S extends Exclude<keyof HTMLElementTagNameMap, AsyncElementTagName> ? never : S): Promise<T>;
+export { AsyncElement, whenReady };
+export type { AsyncElementTagName };

package/dist/async-element.d.ts

@@ -1,5 +1,5 @@
-import type { AppElement } from './app';
-import type { EntityElement } from './entity';
+import type { AppElement } from './app.js';
+import type { EntityBaseElement } from './entity-base.js';
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
  *
@@ -20,11 +20,12 @@ declare class AsyncElement extends HTMLElement {
      */
     get closestApp(): AppElement | null;
     /**
-     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
-     * ancestor. The search starts at the parent, so an element never resolves to itself.
-     * @returns The closest entity element, or `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.
+     * @returns The closest entity-fronting element, or `null`.
      */
-    get closestEntity(): EntityElement | null;
+    get closestEntity(): EntityBaseElement | null;
     /**
      * Called when the element is fully initialized and ready. Subclasses should call this when
      * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
@@ -62,7 +63,8 @@ type AsyncElementTagName = {
 /**
  * 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>`). A component element outside a `<pc-entity>` is
+ * 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.
  * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
@@ -86,7 +88,8 @@ 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>`). A component element outside a `<pc-entity>` is
+ * 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.
  * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).

package/dist/colors.d.cts

@@ -0,0 +1 @@
+export declare const CSS_COLORS: Record<string, string>;

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

@@ -0,0 +1,186 @@
+import type { ButtonComponent } from 'playcanvas';
+import { Color, Vec4 } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * The ButtonComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-button/ | `<pc-button>`} elements.
+ * The ButtonComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * @category Components
+ */
+declare class ButtonComponentElement extends ComponentElement {
+    private _active;
+    private _image;
+    private _hitPadding;
+    private _transitionMode;
+    private _hoverTint;
+    private _pressedTint;
+    private _inactiveTint;
+    private _fadeDuration;
+    private _hoverSpriteAsset;
+    private _hoverSpriteFrame;
+    private _pressedSpriteAsset;
+    private _pressedSpriteFrame;
+    private _inactiveSpriteAsset;
+    private _inactiveSpriteFrame;
+    /** @ignore */
+    constructor();
+    protected getInitialComponentData(): Record<string, any>;
+    /**
+     * Gets the underlying PlayCanvas button component.
+     * @returns The button component.
+     */
+    get component(): ButtonComponent;
+    /**
+     * Sets whether the button is active and responds to input.
+     * @param value - Whether the button is active.
+     */
+    set active(value: boolean);
+    /**
+     * Gets whether the button is active.
+     * @returns Whether the button is active.
+     */
+    get active(): boolean;
+    /**
+     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` whose image
+     * element is used for visual transitions. Defaults to the button's own entity.
+     * @param value - The image entity reference.
+     */
+    set image(value: string);
+    /**
+     * Gets the reference to the `<pc-entity>` whose image element is used for visual transitions.
+     * @returns The image entity reference.
+     */
+    get image(): string;
+    /**
+     * Sets the padding used to expand the button's hit area, as a Vec4 (left, bottom, right, top).
+     * @param value - The hit padding.
+     */
+    set hitPadding(value: Vec4);
+    /**
+     * Gets the padding used to expand the button's hit area.
+     * @returns The hit padding.
+     */
+    get hitPadding(): Vec4;
+    /**
+     * Sets how the button reacts to being hovered/pressed. Can be `tint` or `sprite`. Defaults to
+     * `tint`.
+     * @param value - The transition mode.
+     */
+    set transitionMode(value: 'tint' | 'sprite');
+    /**
+     * Gets how the button reacts to being hovered/pressed.
+     * @returns The transition mode.
+     */
+    get transitionMode(): "tint" | "sprite";
+    /**
+     * Sets the tint color applied to the image entity when the button is hovered (tint transition
+     * mode).
+     * @param value - The hover tint.
+     */
+    set hoverTint(value: Color);
+    /**
+     * Gets the hover tint color.
+     * @returns The hover tint.
+     */
+    get hoverTint(): Color;
+    /**
+     * Sets the tint color applied to the image entity when the button is pressed (tint transition
+     * mode).
+     * @param value - The pressed tint.
+     */
+    set pressedTint(value: Color);
+    /**
+     * Gets the pressed tint color.
+     * @returns The pressed tint.
+     */
+    get pressedTint(): Color;
+    /**
+     * Sets the tint color applied to the image entity when the button is inactive (tint transition
+     * mode).
+     * @param value - The inactive tint.
+     */
+    set inactiveTint(value: Color);
+    /**
+     * Gets the inactive tint color.
+     * @returns The inactive tint.
+     */
+    get inactiveTint(): Color;
+    /**
+     * Sets the duration (in milliseconds) over which tint transitions are applied.
+     * @param value - The fade duration.
+     */
+    set fadeDuration(value: number);
+    /**
+     * Gets the duration over which tint transitions are applied.
+     * @returns The fade duration.
+     */
+    get fadeDuration(): number;
+    /**
+     * Sets the id of the `pc-asset` sprite shown when the button is hovered (sprite transition
+     * mode).
+     * @param value - The hover sprite asset id.
+     */
+    set hoverSpriteAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` sprite shown when the button is hovered.
+     * @returns The hover sprite asset id.
+     */
+    get hoverSpriteAsset(): string;
+    /**
+     * Sets the frame of the hover sprite to show.
+     * @param value - The hover sprite frame.
+     */
+    set hoverSpriteFrame(value: number);
+    /**
+     * Gets the frame of the hover sprite to show.
+     * @returns The hover sprite frame.
+     */
+    get hoverSpriteFrame(): number;
+    /**
+     * Sets the id of the `pc-asset` sprite shown when the button is pressed (sprite transition
+     * mode).
+     * @param value - The pressed sprite asset id.
+     */
+    set pressedSpriteAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` sprite shown when the button is pressed.
+     * @returns The pressed sprite asset id.
+     */
+    get pressedSpriteAsset(): string;
+    /**
+     * Sets the frame of the pressed sprite to show.
+     * @param value - The pressed sprite frame.
+     */
+    set pressedSpriteFrame(value: number);
+    /**
+     * Gets the frame of the pressed sprite to show.
+     * @returns The pressed sprite frame.
+     */
+    get pressedSpriteFrame(): number;
+    /**
+     * Sets the id of the `pc-asset` sprite shown when the button is inactive (sprite transition
+     * mode).
+     * @param value - The inactive sprite asset id.
+     */
+    set inactiveSpriteAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` sprite shown when the button is inactive.
+     * @returns The inactive sprite asset id.
+     */
+    get inactiveSpriteAsset(): string;
+    /**
+     * Sets the frame of the inactive sprite to show.
+     * @param value - The inactive sprite frame.
+     */
+    set inactiveSpriteFrame(value: number);
+    /**
+     * Gets the frame of the inactive sprite to show.
+     * @returns The inactive sprite frame.
+     */
+    get inactiveSpriteFrame(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { ButtonComponentElement };

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

@@ -1,6 +1,6 @@
 import type { ButtonComponent } from 'playcanvas';
 import { Color, Vec4 } from 'playcanvas';
-import { ComponentElement } from './component';
+import { ComponentElement } from './component.js';
 /**
  * The ButtonComponentElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-button/ | `<pc-button>`} elements.