@playcanvas/web-components 0.12.0 → 0.13.1

package/dist/components/component.d.cts

@@ -0,0 +1,82 @@
+import type { Component } from 'playcanvas';
+import { AsyncElement } from '../async-element.cjs';
+/**
+ * Represents a component in the PlayCanvas engine.
+ *
+ * @category Components
+ */
+declare class ComponentElement extends AsyncElement {
+    private _componentName;
+    private _enabled;
+    private _component;
+    private _appElement;
+    /**
+     * The element hosting this component, held so the host's readiness cycles can be observed
+     * even after `closestEntity` would no longer resolve (during teardown).
+     */
+    private _hostElement;
+    /**
+     * The listener re-applying this component when the host's readiness cycles. Held for
+     * removal on disconnect.
+     */
+    private _hostReadyListener;
+    /**
+     * Incremented on every connect and disconnect. connectedCallback captures the value on entry
+     * and abandons itself wherever it resumes from an await if the value has moved on — so a
+     * callback whose element was removed cannot act on a torn-down tree, and one whose element
+     * was removed and re-inserted (which runs a callback of its own) cannot add the component a
+     * second time.
+     */
+    private _connectionGeneration;
+    /**
+     * Creates a new ComponentElement instance.
+     *
+     * @param componentName - The name of the component.
+     * @ignore
+     */
+    constructor(componentName: string);
+    /**
+     * Returns the data the component is created with. Overridden by subclasses to supply the
+     * initial values of their cached properties.
+     *
+     * @returns The initial component data.
+     */
+    protected getInitialComponentData(): {};
+    /**
+     * Creates the component on the host's current entity, removing it first from a previous
+     * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
+     * the entity already has a component of this type — a glTF node arriving with its authored
+     * `render` component, say — warns and leaves `component` null. The element-level warning is
+     * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
+     * production builds, which would otherwise leave a silent null.
+     */
+    private _applyComponent;
+    private _addComponent;
+    /**
+     * Configures the newly added component. Overridden by subclasses whose setup goes beyond
+     * the initial data — child-element handling, asset resolution and the like.
+     */
+    protected initComponent(): void;
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    /**
+     * The PlayCanvas component instance. `null` until the element is ready, and also for an
+     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
+     * element's `ready()` promise before accessing it.
+     * @returns The component instance, or `null`.
+     */
+    get component(): Component | null;
+    /**
+     * Sets the enabled state of the component.
+     * @param value - The enabled state of the component.
+     */
+    set enabled(value: boolean);
+    /**
+     * Gets the enabled state of the component.
+     * @returns The enabled state of the component.
+     */
+    get enabled(): boolean;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { ComponentElement };

package/dist/components/component.d.ts

@@ -1,5 +1,5 @@
 import type { Component } from 'playcanvas';
-import { AsyncElement } from '../async-element';
+import { AsyncElement } from '../async-element.js';
 /**
  * Represents a component in the PlayCanvas engine.
  *

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

@@ -0,0 +1,316 @@
+import type { ElementComponent } from 'playcanvas';
+import { Color, Vec2, Vec4 } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * The ElementComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-element/ | `<pc-element>`} elements.
+ * The ElementComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * @category Components
+ */
+declare class ElementComponentElement extends ComponentElement {
+    private _anchor;
+    private _autoWidth;
+    private _autoHeight;
+    private _autoFitWidth;
+    private _autoFitHeight;
+    private _color;
+    private _enableMarkup;
+    private _fontAsset;
+    private _fontSize;
+    private _maxFontSize;
+    private _minFontSize;
+    private _height;
+    private _lineHeight;
+    private _margin;
+    private _mask;
+    private _opacity;
+    private _pivot;
+    private _pixelsPerUnit;
+    private _spriteAsset;
+    private _spriteFrame;
+    private _text;
+    private _textureAsset;
+    private _type;
+    private _useInput;
+    private _width;
+    private _wrapLines;
+    /** @ignore */
+    constructor();
+    protected initComponent(): void;
+    protected getInitialComponentData(): Record<string, any>;
+    /**
+     * Gets the underlying PlayCanvas element component.
+     * @returns The element component.
+     */
+    get component(): ElementComponent;
+    /**
+     * Sets the anchor of the element component.
+     * @param value - The anchor.
+     */
+    set anchor(value: Vec4);
+    /**
+     * Gets the anchor of the element component.
+     * @returns The anchor.
+     */
+    get anchor(): Vec4;
+    /**
+     * Sets whether the element component should automatically adjust its width to the text content
+     * (text elements only).
+     * @param value - Whether to automatically adjust the width.
+     */
+    set autoWidth(value: boolean);
+    /**
+     * Gets whether the element component should automatically adjust its width.
+     * @returns Whether to automatically adjust the width.
+     */
+    get autoWidth(): boolean;
+    /**
+     * Sets whether the element component should automatically adjust its height to the text content
+     * (text elements only).
+     * @param value - Whether to automatically adjust the height.
+     */
+    set autoHeight(value: boolean);
+    /**
+     * Gets whether the element component should automatically adjust its height.
+     * @returns Whether to automatically adjust the height.
+     */
+    get autoHeight(): boolean;
+    /**
+     * Sets the color of the element component.
+     * @param value - The color.
+     */
+    set color(value: Color);
+    /**
+     * Gets the color of the element component.
+     * @returns The color.
+     */
+    get color(): Color;
+    /**
+     * Sets whether the element component should use markup.
+     * @param value - Whether to enable markup.
+     */
+    set enableMarkup(value: boolean);
+    /**
+     * Gets whether the element component should use markup.
+     * @returns Whether markup is enabled.
+     */
+    get enableMarkup(): boolean;
+    /**
+     * Sets the id of the `pc-asset` to use for the font (text elements).
+     * @param value - The font asset ID.
+     */
+    set fontAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the font.
+     * @returns The font asset ID.
+     */
+    get fontAsset(): string;
+    /**
+     * Sets the font size of the element component.
+     * @param value - The font size.
+     */
+    set fontSize(value: number);
+    /**
+     * Gets the font size of the element component.
+     * @returns The font size.
+     */
+    get fontSize(): number;
+    /**
+     * Sets the height of the element component.
+     * @param value - The height.
+     */
+    set height(value: number);
+    /**
+     * Gets the height of the element component.
+     * @returns The height.
+     */
+    get height(): number;
+    /**
+     * Sets the line height of the element component.
+     * @param value - The line height.
+     */
+    set lineHeight(value: number);
+    /**
+     * Gets the line height of the element component.
+     * @returns The line height.
+     */
+    get lineHeight(): number;
+    /**
+     * Sets the margin of the element component (used to inset the element from stretched anchors).
+     * @param value - The margin as a Vec4 (left, bottom, right, top).
+     */
+    set margin(value: Vec4 | null);
+    /**
+     * Gets the margin of the element component.
+     * @returns The margin.
+     */
+    get margin(): Vec4 | null;
+    /**
+     * Sets whether the element component is a mask, clipping its descendants to its bounds (image
+     * elements only).
+     * @param value - Whether the element is a mask.
+     */
+    set mask(value: boolean);
+    /**
+     * Gets whether the element component is a mask.
+     * @returns Whether the element is a mask.
+     */
+    get mask(): boolean;
+    /**
+     * Sets the opacity of the element component.
+     * @param value - The opacity (0 to 1).
+     */
+    set opacity(value: number);
+    /**
+     * Gets the opacity of the element component.
+     * @returns The opacity.
+     */
+    get opacity(): number;
+    /**
+     * Sets the pivot of the element component.
+     * @param value - The pivot.
+     */
+    set pivot(value: Vec2);
+    /**
+     * Gets the pivot of the element component.
+     * @returns The pivot.
+     */
+    get pivot(): Vec2;
+    /**
+     * Sets the number of pixels per unit to use when rendering a sprite (image elements only).
+     * @param value - The pixels per unit.
+     */
+    set pixelsPerUnit(value: number | null);
+    /**
+     * Gets the number of pixels per unit used when rendering a sprite.
+     * @returns The pixels per unit.
+     */
+    get pixelsPerUnit(): number | null;
+    /**
+     * Sets the id of the `pc-asset` to use for the sprite (image elements only).
+     * @param value - The sprite asset ID.
+     */
+    set spriteAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the sprite.
+     * @returns The sprite asset ID.
+     */
+    get spriteAsset(): string;
+    /**
+     * Sets the frame of the sprite to render (image elements only).
+     * @param value - The sprite frame index.
+     */
+    set spriteFrame(value: number);
+    /**
+     * Gets the frame of the sprite to render.
+     * @returns The sprite frame index.
+     */
+    get spriteFrame(): number;
+    /**
+     * Sets the text of the element component.
+     * @param value - The text.
+     */
+    set text(value: string);
+    /**
+     * Gets the text of the element component.
+     * @returns The text.
+     */
+    get text(): string;
+    /**
+     * Sets the id of the `pc-asset` to use for the texture (image elements only).
+     * @param value - The texture asset ID.
+     */
+    set textureAsset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the texture.
+     * @returns The texture asset ID.
+     */
+    get textureAsset(): string;
+    /**
+     * Sets the type of the element component.
+     * @param value - The type.
+     */
+    set type(value: 'group' | 'image' | 'text');
+    /**
+     * Gets the type of the element component.
+     * @returns The type.
+     */
+    get type(): 'group' | 'image' | 'text';
+    /**
+     * Sets whether the element component accepts input events (required for buttons and scrolling).
+     * @param value - Whether the element accepts input.
+     */
+    set useInput(value: boolean);
+    /**
+     * Gets whether the element component accepts input events.
+     * @returns Whether the element accepts input.
+     */
+    get useInput(): boolean;
+    /**
+     * Sets the width of the element component.
+     * @param value - The width.
+     */
+    set width(value: number);
+    /**
+     * Gets the width of the element component.
+     * @returns The width.
+     */
+    get width(): number;
+    /**
+     * Sets whether the element component should wrap lines.
+     * @param value - Whether to wrap lines.
+     */
+    set wrapLines(value: boolean);
+    /**
+     * Gets whether the element component should wrap lines.
+     * @returns Whether to wrap lines.
+     */
+    get wrapLines(): boolean;
+    /**
+     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
+     * so the text fits within the element's width. Requires `auto-width` to be `false`.
+     * @param value - Whether to auto-fit the width.
+     */
+    set autoFitWidth(value: boolean);
+    /**
+     * Gets whether a text element automatically reduces its font size to fit its width.
+     * @returns Whether the width is auto-fit.
+     */
+    get autoFitWidth(): boolean;
+    /**
+     * Sets whether a text element should automatically reduce its font size (down to `min-font-size`)
+     * so the text fits within the element's height. Requires `auto-height` to be `false`.
+     * @param value - Whether to auto-fit the height.
+     */
+    set autoFitHeight(value: boolean);
+    /**
+     * Gets whether a text element automatically reduces its font size to fit its height.
+     * @returns Whether the height is auto-fit.
+     */
+    get autoFitHeight(): boolean;
+    /**
+     * Sets the smallest font size a text element may use when auto-fitting.
+     * @param value - The minimum font size.
+     */
+    set minFontSize(value: number);
+    /**
+     * Gets the smallest font size a text element may use when auto-fitting.
+     * @returns The minimum font size.
+     */
+    get minFontSize(): number;
+    /**
+     * Sets the largest font size a text element may use when auto-fitting.
+     * @param value - The maximum font size.
+     */
+    set maxFontSize(value: number);
+    /**
+     * Gets the largest font size a text element may use when auto-fitting.
+     * @returns The maximum font size.
+     */
+    get maxFontSize(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { ElementComponentElement };

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

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

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

@@ -0,0 +1,108 @@
+import type { GSplatComponent } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * The GSplatComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-gsplat/ | `<pc-gsplat>`} elements.
+ * The GSplatComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * @category Components
+ */
+declare class GSplatComponentElement extends ComponentElement {
+    private _asset;
+    private _castShadows;
+    private _lodBaseDistance;
+    private _lodMultiplier;
+    private _lodRangeMin;
+    private _lodRangeMax;
+    /** @ignore */
+    constructor();
+    protected getInitialComponentData(): {
+        asset: import("playcanvas").Asset | null | undefined;
+        castShadows: boolean;
+        lodBaseDistance: number;
+        lodMultiplier: number;
+        lodRangeMin: number;
+        lodRangeMax: number;
+    };
+    /**
+     * Gets the underlying PlayCanvas gsplat component.
+     * @returns The gsplat component.
+     */
+    get component(): GSplatComponent;
+    /**
+     * Sets id of the `pc-asset` to use for the splat.
+     * @param value - The asset ID.
+     */
+    set asset(value: string);
+    /**
+     * Gets the id of the `pc-asset` to use for the splat.
+     * @returns The asset ID.
+     */
+    get asset(): string;
+    /**
+     * Sets whether the splat casts shadows.
+     * @param value - Whether the splat casts shadows.
+     */
+    set castShadows(value: boolean);
+    /**
+     * Gets whether the splat casts shadows.
+     * @returns Whether the splat casts shadows.
+     */
+    get castShadows(): boolean;
+    /**
+     * Sets the base distance for the first LOD transition (LOD 0 to LOD 1). Splats closer than
+     * this distance use the highest quality LOD. Each subsequent LOD level transitions at a
+     * progressively larger distance, controlled by {@link lodMultiplier}. Clamped to a minimum of
+     * 0.1. Defaults to 5. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
+     * @param value - The LOD base distance.
+     */
+    set lodBaseDistance(value: number);
+    /**
+     * Gets the base distance for the first LOD transition.
+     * @returns The LOD base distance.
+     */
+    get lodBaseDistance(): number;
+    /**
+     * Sets the multiplier between successive LOD distance thresholds. Each LOD level transitions
+     * at this factor times the previous level's distance, creating a geometric progression. Lower
+     * values keep higher quality at distance; higher values switch to coarser LODs sooner. Clamped
+     * to a minimum of 1.2. Defaults to 3. Only affects assets that contain LOD levels (e.g.
+     * `.lod-meta.json`).
+     * @param value - The LOD multiplier.
+     */
+    set lodMultiplier(value: number);
+    /**
+     * Gets the multiplier between successive LOD distance thresholds.
+     * @returns The LOD multiplier.
+     */
+    get lodMultiplier(): number;
+    /**
+     * Sets the minimum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
+     * never goes finer (lower index) than this value. Raising it avoids downloading the highest
+     * quality (largest) LOD files. Defaults to 0. Only affects assets that contain LOD levels (e.g.
+     * `.lod-meta.json`).
+     * @param value - The minimum LOD index.
+     */
+    set lodRangeMin(value: number);
+    /**
+     * Gets the minimum allowed LOD index.
+     * @returns The minimum LOD index.
+     */
+    get lodRangeMin(): number;
+    /**
+     * Sets the maximum allowed LOD index (inclusive). The LOD selected by distance is clamped so it
+     * never goes coarser (higher index) than this value. The default of 99 effectively means "no
+     * cap". Defaults to 99. Only affects assets that contain LOD levels (e.g. `.lod-meta.json`).
+     * @param value - The maximum LOD index.
+     */
+    set lodRangeMax(value: number);
+    /**
+     * Gets the maximum allowed LOD index.
+     * @returns The maximum LOD index.
+     */
+    get lodRangeMax(): number;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { GSplatComponentElement };

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

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

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

@@ -0,0 +1,110 @@
+import type { LayoutChildComponent } from 'playcanvas';
+import { ComponentElement } from './component.cjs';
+/**
+ * The LayoutChildComponentElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
+ * The LayoutChildComponentElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * @category Components
+ */
+declare class LayoutChildComponentElement extends ComponentElement {
+    private _minWidth;
+    private _minHeight;
+    private _maxWidth;
+    private _maxHeight;
+    private _fitWidthProportion;
+    private _fitHeightProportion;
+    private _excludeFromLayout;
+    /** @ignore */
+    constructor();
+    protected getInitialComponentData(): {
+        minWidth: number;
+        minHeight: number;
+        maxWidth: number | null;
+        maxHeight: number | null;
+        fitWidthProportion: number;
+        fitHeightProportion: number;
+        excludeFromLayout: boolean;
+    };
+    /**
+     * Gets the underlying PlayCanvas layout child component.
+     * @returns The layout child component.
+     */
+    get component(): LayoutChildComponent;
+    /**
+     * Sets the minimum width the element should be laid out with.
+     * @param value - The minimum width.
+     */
+    set minWidth(value: number);
+    /**
+     * Gets the minimum width the element should be laid out with.
+     * @returns The minimum width.
+     */
+    get minWidth(): number;
+    /**
+     * Sets the minimum height the element should be laid out with.
+     * @param value - The minimum height.
+     */
+    set minHeight(value: number);
+    /**
+     * Gets the minimum height the element should be laid out with.
+     * @returns The minimum height.
+     */
+    get minHeight(): number;
+    /**
+     * Sets the maximum width the element should be laid out with (or `null` for no limit).
+     * @param value - The maximum width.
+     */
+    set maxWidth(value: number | null);
+    /**
+     * Gets the maximum width the element should be laid out with.
+     * @returns The maximum width.
+     */
+    get maxWidth(): number | null;
+    /**
+     * Sets the maximum height the element should be laid out with (or `null` for no limit).
+     * @param value - The maximum height.
+     */
+    set maxHeight(value: number | null);
+    /**
+     * Gets the maximum height the element should be laid out with.
+     * @returns The maximum height.
+     */
+    get maxHeight(): number | null;
+    /**
+     * Sets the proportion of the container's spare width this element should take (when the layout
+     * group's `width-fitting` is set to stretch or shrink).
+     * @param value - The fit width proportion.
+     */
+    set fitWidthProportion(value: number);
+    /**
+     * Gets the proportion of the container's spare width this element should take.
+     * @returns The fit width proportion.
+     */
+    get fitWidthProportion(): number;
+    /**
+     * Sets the proportion of the container's spare height this element should take (when the layout
+     * group's `height-fitting` is set to stretch or shrink).
+     * @param value - The fit height proportion.
+     */
+    set fitHeightProportion(value: number);
+    /**
+     * Gets the proportion of the container's spare height this element should take.
+     * @returns The fit height proportion.
+     */
+    get fitHeightProportion(): number;
+    /**
+     * Sets whether the element should be excluded from the layout (and thus not take up space).
+     * @param value - Whether to exclude the element from layout.
+     */
+    set excludeFromLayout(value: boolean);
+    /**
+     * Gets whether the element is excluded from the layout.
+     * @returns Whether the element is excluded from layout.
+     */
+    get excludeFromLayout(): boolean;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { LayoutChildComponentElement };

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

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