@playcanvas/web-components 0.19.0 → 0.21.0

package/src/components/particle-system-component.ts

@@ -1,6 +1,7 @@
-import type { ParticleSystemComponent } from 'playcanvas';
+import type { Asset, ParticleSystemComponent } from 'playcanvas';
 
 import { useAsset } from '../asset';
+import { AssetBinding } from '../asset-binding';
 
 import { ComponentElement } from './component';
 
@@ -18,9 +19,17 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class ParticleSystemComponentElement extends ComponentElement {
+class ParticleSystemComponentElement extends ComponentElement<ParticleSystemComponent> {
     private _asset = '';
 
+    /**
+     * The subscription to the current config asset while its load is in flight. Rebinding
+     * supersedes it and disconnect cancels it, so a superseded config — an earlier asset that
+     * finishes loading after its replacement, or a callback left behind by a previous
+     * connection — can never configure the component.
+     */
+    private _binding = new AssetBinding();
+
     /** @ignore */
     constructor() {
         super('particlesystem');
@@ -28,28 +37,54 @@ class ParticleSystemComponentElement extends ComponentElement {
 
     protected getInitialComponentData() {
         const asset = useAsset(this._asset);
-        // A lazy config has no resource yet - _loadAsset applies it once the load completes
+        // A lazy config has no resource yet - the config binding applies it once the load
+        // completes
         if (!asset || !asset.resource) {
             return {};
         }
 
-        if ((asset.resource as any).colorMapAsset) {
-            const id = (asset.resource as any).colorMapAsset;
-            const colorMapAsset = useAsset(id)?.id;
-            if (colorMapAsset) {
-                (asset.resource as any).colorMapAsset = colorMapAsset;
-            }
+        this._resolveColorMap(asset.resource);
+        return asset.resource;
+    }
+
+    protected initComponent() {
+        // A loaded config already arrived through getInitialComponentData - the binding is only
+        // needed for a load still in flight. Resolution here also starts a lazy config's load.
+        const asset = useAsset(this._asset);
+        if (asset && !asset.loaded) {
+            this._bindConfig();
         }
+    }
 
-        return asset.resource;
+    disconnectedCallback() {
+        // The binding dies with the connection, so a config that finishes loading later cannot
+        // configure the component a reconnection creates - that connection binds afresh.
+        this._binding.cancel();
+        super.disconnectedCallback();
     }
 
     /**
-     * Gets the underlying PlayCanvas particle system component.
-     * @returns The particle system component.
+     * Gets the underlying PlayCanvas particle system component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The particle system component, or `null`.
      */
-    get component(): ParticleSystemComponent {
-        return super.component as ParticleSystemComponent;
+    get component(): ParticleSystemComponent | null {
+        return super.component;
+    }
+
+    /**
+     * Rewrites the config's `colorMapAsset` from the `pc-asset` id it is authored with to the
+     * engine asset id the component resolves, starting the texture's load if it is lazy. The
+     * rewrite is in place, so a config applied again — a host cycle, a reconnection — is already
+     * resolved and passes through unchanged.
+     */
+    private _resolveColorMap(resource: any) {
+        if (resource.colorMapAsset) {
+            const colorMapAsset = useAsset(resource.colorMapAsset)?.id;
+            if (colorMapAsset) {
+                resource.colorMapAsset = colorMapAsset;
+            }
+        }
     }
 
     private applyConfig(resource: any) {
@@ -57,6 +92,8 @@ class ParticleSystemComponentElement extends ComponentElement {
             return;
         }
 
+        this._resolveColorMap(resource);
+
         // Set all the config properties on the component
         for (const key in resource) {
             if (Object.hasOwn(resource, key)) {
@@ -65,21 +102,10 @@ class ParticleSystemComponentElement extends ComponentElement {
         }
     }
 
-    private async _loadAsset() {
-        await this.closestApp?.ready();
-
-        const asset = useAsset(this._asset);
-        if (!asset) {
-            return;
-        }
-
-        if (asset.loaded) {
-            this.applyConfig(asset.resource);
-        } else {
-            asset.once('load', () => {
-                this.applyConfig(asset.resource);
-            });
-        }
+    private _bindConfig() {
+        this._binding.bind(this._asset, {
+            load: (asset: Asset) => this.applyConfig(asset.resource)
+        });
     }
 
     /**
@@ -89,7 +115,7 @@ class ParticleSystemComponentElement extends ComponentElement {
     set asset(value: string) {
         this._asset = value;
         if (this.isConnected) {
-            this._loadAsset();
+            this._bindConfig();
         }
     }
 

package/src/components/render-component.ts

@@ -24,7 +24,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class RenderComponentElement extends ComponentElement {
+class RenderComponentElement extends ComponentElement<RenderComponent> {
     private _castShadows = true;
 
     private _material = '';
@@ -48,11 +48,12 @@ class RenderComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas render component.
-     * @returns The render component.
+     * Gets the underlying PlayCanvas render component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The render component, or `null`.
      */
-    get component(): RenderComponent {
-        return super.component as RenderComponent;
+    get component(): RenderComponent | null {
+        return super.component;
     }
 
     /**

package/src/components/rigid-body-component.ts

@@ -20,7 +20,7 @@ import { ComponentElement } from './component';
  *
  * @category Components
  */
-class RigidBodyComponentElement extends ComponentElement {
+class RigidBodyComponentElement extends ComponentElement<RigidBodyComponent> {
     /**
      * The angular damping of the rigidbody.
      */
@@ -86,11 +86,12 @@ class RigidBodyComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas rigidbody component.
-     * @returns The rigidbody component.
+     * Gets the underlying PlayCanvas rigidbody component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The rigidbody component, or `null`.
      */
-    get component(): RigidBodyComponent {
-        return super.component as RigidBodyComponent;
+    get component(): RigidBodyComponent | null {
+        return super.component;
     }
 
     set angularDamping(value: number) {

package/src/components/screen-component.ts

@@ -28,7 +28,7 @@ const scaleModes = new Map<'none' | 'blend', string>([
  *
  * @category Components
  */
-class ScreenComponentElement extends ComponentElement {
+class ScreenComponentElement extends ComponentElement<ScreenComponent> {
     private _screenSpace = false;
 
     private _resolution: Vec2 = new Vec2(640, 320);
@@ -58,11 +58,12 @@ class ScreenComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas screen component.
-     * @returns The screen component.
+     * Gets the underlying PlayCanvas screen component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The screen component, or `null`.
      */
-    get component(): ScreenComponent {
-        return super.component as ScreenComponent;
+    get component(): ScreenComponent | null {
+        return super.component;
     }
 
     set priority(value: number) {

package/src/components/script-component.ts

@@ -2,8 +2,8 @@ import type { ScriptComponent, Script } from 'playcanvas';
 import { Color, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { useAsset } from '../asset';
+import { findEntityElement, getEntity, idHint, unresolvedCause } from '../entity-reference';
 import {
-    getEntity,
     parseBool,
     parseColor,
     parseComponents,
@@ -107,10 +107,11 @@ const camelToKebab = (name: string): string => {
 
 /**
  * A conversion applied to a script attribute value carrying an explicit type prefix. Receives the
- * text after the prefix plus the raw value, and returns the raw value (having warned) when it
- * cannot resolve or parse it — callers rely on that identity to tell failure from success.
+ * text after the prefix, the raw value, and the element the value is declared under — which
+ * scopes entity references — and returns the raw value (having warned) when it cannot resolve or
+ * parse it — callers rely on that identity to tell failure from success.
  */
-type Conversion = (rest: string, raw: string) => any;
+type Conversion = (rest: string, raw: string, from: Element) => any;
 
 /**
  * Resolves an `asset:` prefix to the Asset created by the `pc-asset` element with that id.
@@ -128,18 +129,25 @@ const assetConversion: Conversion = (rest, raw) => {
 };
 
 /**
- * Resolves an `entity:` prefix to the Entity backing a `pc-entity` element. The reference can be a
- * CSS selector, an element id or an entity name.
+ * Resolves an `entity:` prefix to the Entity backing a `pc-entity`, `pc-model` or `pc-node`
+ * element. The reference is a name — resolved against the nearest enclosing entity first, then
+ * outward, then the document — or a document-wide `#` selector. The failure warning names which
+ * of the three causes ({@link unresolvedCause}) it hit.
  * @param rest - The entity reference.
  * @param raw - The raw value, returned unchanged when the reference does not resolve.
+ * @param from - The element the value is declared under, which scopes the reference.
  * @returns The entity, or `raw`.
  */
-const entityConversion: Conversion = (rest, raw) => {
-    const entity = getEntity(rest);
+const entityConversion: Conversion = (rest, raw, from) => {
+    const entity = getEntity(rest, from);
     if (entity) {
         return entity;
     }
-    console.warn(`Unable to resolve '${raw}' in script attributes - no pc-entity found matching '${rest}'.`);
+    const element = findEntityElement(rest, from);
+    const hint = element ? '' : idHint(rest, 'entity:');
+    console.warn(
+        `Unable to resolve '${raw}' in script attributes - ${unresolvedCause(element)}.${hint ? ` ${hint}` : ''}`
+    );
     return raw;
 };
 
@@ -255,7 +263,7 @@ export type ScriptNameChangeEvent = {
  *
  * @category Components
  */
-class ScriptComponentElement extends ComponentElement {
+class ScriptComponentElement extends ComponentElement<ScriptComponent> {
     private observer: MutationObserver;
 
     /** @ignore */
@@ -298,8 +306,10 @@ class ScriptComponentElement extends ComponentElement {
     /**
      * Recursively converts raw attribute data into proper PlayCanvas types. Supported conversions:
      * - "asset:id" → the Asset created by the `pc-asset` element with that id
-     * - "entity:ref" → the Entity backing a `pc-entity` element. The reference can be a CSS
-     *   selector, an element id or an entity name.
+     * - "entity:ref" → the Entity backing a `pc-entity`, `pc-model` or `pc-node` element. The
+     *   reference is a name, resolved against this element's nearest enclosing entity first,
+     *   then outward, then the document — or a document-wide `#` selector (`entity:#id`). A bare
+     *   value is always a name, never an id.
      * - "vec2:1 2" → new Vec2(1, 2)
      * - "vec3:1 2 3" → new Vec3(1, 2, 3)
      * - "vec4:1 2 3 4" → new Vec4(1, 2, 3, 4)
@@ -313,7 +323,7 @@ class ScriptComponentElement extends ComponentElement {
     private convertAttributes(item: any): any {
         if (typeof item === 'string') {
             const match = matchConversion(item);
-            return match ? match.convert(match.rest, item) : item;
+            return match ? match.convert(match.rest, item, this) : item;
         }
 
         if (Array.isArray(item)) {
@@ -730,11 +740,12 @@ class ScriptComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas script component.
-     * @returns The script component.
+     * Gets the underlying PlayCanvas script component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The script component, or `null`.
      */
-    get component(): ScriptComponent {
-        return super.component as ScriptComponent;
+    get component(): ScriptComponent | null {
+        return super.component;
     }
 }
 

package/src/components/script-instance.ts

@@ -15,7 +15,9 @@ import { parseBool } from '../parse';
  *   Values are parsed according to the type of the attribute's current value — initially the
  *   script's declared default (numbers, booleans, strings, Vec2/3/4, Color, Quat as Euler
  *   angles) — and the `asset:`/`entity:`/`vec2:`/`vec3:`/`vec4:`/`color:` prefixes may be used
- *   to be explicit.
+ *   to be explicit. An `entity:` reference is an entity name — resolved against the nearest
+ *   enclosing entity first, then outward, then the document — or a document-wide `#` selector
+ *   (`entity:#id`); a bare value is always a name, never an element id.
  * - **The `attributes` JSON attribute**: an object supporting nested structures and attribute
  *   names that collide with reserved HTML attribute names (e.g. `title`).
  *
@@ -31,7 +33,8 @@ import { parseBool } from '../parse';
  *
  * @elementSummary The `<pc-script-instance>` element attaches one script class, named by `name`, to
  * the entity of its parent `<pc-script>`. Its other attributes set script attributes of the same
- * name, and `attributes` takes a JSON object instead. Must be a direct child of `<pc-script>`.
+ * name, and `attributes` takes a JSON object instead. An `entity:` value is an entity name —
+ * write `entity:#id` for an element id. Must be a direct child of `<pc-script>`.
  *
  * @fires {CustomEvent} scriptattributeschange - Fired when the script's attributes change. The
  * `detail` carries the new `attributes` object. Bubbles.
@@ -54,9 +57,11 @@ class ScriptInstanceElement extends AsyncElement {
     /**
      * Sets the attributes of the script as an object. Values are converted with the same rules
      * as the `attributes` attribute: `asset:`/`entity:` references and `vec2:`/`vec3:`/`vec4:`/
-     * `color:` prefixed strings are resolved, and a plain numeric array is converted to the
-     * type of the attribute it targets when that attribute currently holds a Vec2, Vec3, Vec4
-     * or Color.
+     * `color:` prefixed strings are resolved (an entity name against the nearest enclosing
+     * entity first, then outward, then the document — or a document-wide `#` selector; a bare
+     * value is always a name, never an element id), and a plain numeric array is converted to
+     * the type of the attribute it targets when that attribute currently holds a Vec2, Vec3,
+     * Vec4 or Color.
      * @param value - The attributes of the script.
      */
     set scriptAttributes(value: Record<string, any>) {
@@ -70,7 +75,10 @@ class ScriptInstanceElement extends AsyncElement {
     }
 
     /**
-     * Gets the attributes of the script.
+     * Gets the attributes of the script as an object whose `asset:`, `entity:`, `vec2:`, `vec3:`,
+     * `vec4:` and `color:` prefixed values are resolved when applied — an `entity:` value being
+     * an entity name (nearest enclosing entity first, then outward, then the document) or a
+     * document-wide `#` selector (`entity:#id`), never a bare element id.
      * @returns The attributes of the script.
      */
     get scriptAttributes(): Record<string, any> {

package/src/components/scroll-view-component.ts

@@ -8,7 +8,8 @@ import {
     Vec2
 } from 'playcanvas';
 
-import { getEntity, parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
+import { resolveEntity } from '../entity-reference';
+import { parseBool, parseEnum, parseNumber, parseVec2 } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -37,7 +38,7 @@ const visibilities = new Map<'always' | 'when-required', number>([
  *
  * @category Components
  */
-class ScrollViewComponentElement extends ComponentElement {
+class ScrollViewComponentElement extends ComponentElement<ScrollViewComponent> {
     private _horizontal = true;
 
     private _vertical = true;
@@ -82,22 +83,22 @@ class ScrollViewComponentElement extends ComponentElement {
             verticalScrollbarVisibility: visibilities.get(this._verticalScrollbarVisibility)
         };
 
-        const viewport = getEntity(this._viewport);
+        const viewport = resolveEntity(this._viewport, this, 'viewport', 'reference ignored');
         if (viewport) {
             data.viewportEntity = viewport;
         }
 
-        const content = getEntity(this._content);
+        const content = resolveEntity(this._content, this, 'content', 'reference ignored');
         if (content) {
             data.contentEntity = content;
         }
 
-        const horizontalScrollbar = getEntity(this._horizontalScrollbar);
+        const horizontalScrollbar = resolveEntity(this._horizontalScrollbar, this, 'horizontal-scrollbar', 'reference ignored');
         if (horizontalScrollbar) {
             data.horizontalScrollbarEntity = horizontalScrollbar;
         }
 
-        const verticalScrollbar = getEntity(this._verticalScrollbar);
+        const verticalScrollbar = resolveEntity(this._verticalScrollbar, this, 'vertical-scrollbar', 'reference ignored');
         if (verticalScrollbar) {
             data.verticalScrollbarEntity = verticalScrollbar;
         }
@@ -106,11 +107,12 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas scroll view component.
-     * @returns The scroll view component.
+     * Gets the underlying PlayCanvas scroll view component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scroll view component, or `null`.
      */
-    get component(): ScrollViewComponent {
-        return super.component as ScrollViewComponent;
+    get component(): ScrollViewComponent | null {
+        return super.component;
     }
 
     /**
@@ -294,20 +296,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * viewport, which clips the content to the scroll view's bounds.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport, which clips the content to the scroll view's
+     * bounds. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @param value - The viewport entity reference.
      */
     set viewport(value: string) {
         this._viewport = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.viewportEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'viewport', 'reference ignored');
+            if (entity) {
+                this.component.viewportEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the viewport.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the viewport.
      * @returns The viewport entity reference.
      */
     get viewport() {
@@ -315,20 +322,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * content, which is moved as the scroll view is scrolled.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content, which is moved as the scroll view is
+     * scrolled. An exact name resolves against the nearest enclosing entity first, then outward,
+     * then the document. A non-empty reference that does not resolve warns and is ignored.
      * @param value - The content entity reference.
      */
     set content(value: string) {
         this._content = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.contentEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'content', 'reference ignored');
+            if (entity) {
+                this.component.contentEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the content.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the content.
      * @returns The content entity reference.
      */
     get content() {
@@ -336,20 +348,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the horizontal `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The horizontal scrollbar entity reference.
      */
     set horizontalScrollbar(value: string) {
         this._horizontalScrollbar = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.horizontalScrollbarEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'horizontal-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.horizontalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the horizontal scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the horizontal scrollbar.
      * @returns The horizontal scrollbar entity reference.
      */
     get horizontalScrollbar() {
@@ -357,20 +374,25 @@ class ScrollViewComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` containing
-     * the vertical `<pc-scrollbar>`.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical `<pc-scrollbar>`. An exact name resolves
+     * against the nearest enclosing entity first, then outward, then the document. A non-empty
+     * reference that does not resolve warns and is ignored.
      * @param value - The vertical scrollbar entity reference.
      */
     set verticalScrollbar(value: string) {
         this._verticalScrollbar = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.verticalScrollbarEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'vertical-scrollbar', 'reference ignored');
+            if (entity) {
+                this.component.verticalScrollbarEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` containing the vertical scrollbar.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity containing the vertical scrollbar.
      * @returns The vertical scrollbar entity reference.
      */
     get verticalScrollbar() {

package/src/components/scrollbar-component.ts

@@ -1,7 +1,8 @@
 import type { ScrollbarComponent } from 'playcanvas';
 import { ORIENTATION_HORIZONTAL, ORIENTATION_VERTICAL } from 'playcanvas';
 
-import { getEntity, parseEnum, parseNumber } from '../parse';
+import { resolveEntity } from '../entity-reference';
+import { parseEnum, parseNumber } from '../parse';
 
 import { ComponentElement } from './component';
 
@@ -24,7 +25,7 @@ const orientations = new Map<'horizontal' | 'vertical', number>([
  *
  * @category Components
  */
-class ScrollbarComponentElement extends ComponentElement {
+class ScrollbarComponentElement extends ComponentElement<ScrollbarComponent> {
     private _orientation: 'horizontal' | 'vertical' = 'horizontal';
 
     private _value = 0;
@@ -45,7 +46,7 @@ class ScrollbarComponentElement extends ComponentElement {
             handleSize: this._handleSize
         };
 
-        const handle = getEntity(this._handle);
+        const handle = resolveEntity(this._handle, this, 'handle', 'reference ignored');
         if (handle) {
             data.handleEntity = handle;
         }
@@ -54,11 +55,12 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     /**
-     * Gets the underlying PlayCanvas scrollbar component.
-     * @returns The scrollbar component.
+     * Gets the underlying PlayCanvas scrollbar component. `null` until the element is
+     * ready — see {@link ComponentElement.component}.
+     * @returns The scrollbar component, or `null`.
      */
-    get component(): ScrollbarComponent {
-        return super.component as ScrollbarComponent;
+    get component(): ScrollbarComponent | null {
+        return super.component;
     }
 
     /**
@@ -120,20 +122,25 @@ class ScrollbarComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets the reference (CSS selector, element id or entity name) to the `<pc-entity>` used as the
-     * scrollbar handle.
+     * Sets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle. An exact name resolves against the
+     * nearest enclosing entity first, then outward, then the document. A non-empty reference that
+     * does not resolve warns and is ignored.
      * @param value - The handle entity reference.
      */
     set handle(value: string) {
         this._handle = value;
-        const entity = getEntity(value);
-        if (this.component && entity) {
-            this.component.handleEntity = entity;
+        if (this.component) {
+            const entity = resolveEntity(value, this, 'handle', 'reference ignored');
+            if (entity) {
+                this.component.handleEntity = entity;
+            }
         }
     }
 
     /**
-     * Gets the reference to the `<pc-entity>` used as the scrollbar handle.
+     * Gets the reference (a `pc-entity`, `pc-model` or `pc-node` name, or a document-wide `#`
+     * selector) to the entity used as the scrollbar handle.
      * @returns The handle entity reference.
      */
     get handle() {