@playcanvas/web-components 0.8.2 → 0.10.0

package/src/model.ts

@@ -97,10 +97,10 @@ class ModelElement extends AsyncElement {
         return ['asset'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'asset':
-                this.asset = newValue;
+                this.asset = newValue ?? '';
                 break;
         }
     }
@@ -108,4 +108,10 @@ class ModelElement extends AsyncElement {
 
 customElements.define('pc-model', ModelElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-model': ModelElement;
+    }
+}
+
 export { ModelElement };

package/src/module.ts

@@ -5,6 +5,16 @@ import { basisInitialize, WasmModule } from 'playcanvas';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
  * The ModuleElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * Note that these attributes are read once when the element is created, so changing them later
+ * has no effect.
+ *
+ * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
+ * `Ammo`.
+ * @attribute {string} glue - The URL of the module's glue script.
+ * @attribute {string} wasm - The URL of the module's WebAssembly binary.
+ * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
+ * WebAssembly is unavailable.
  */
 class ModuleElement extends HTMLElement {
     private loadPromise: Promise<void>;
@@ -40,4 +50,10 @@ class ModuleElement extends HTMLElement {
 
 customElements.define('pc-module', ModuleElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-module': ModuleElement;
+    }
+}
+
 export { ModuleElement };

package/src/parse.ts

@@ -0,0 +1,298 @@
+/**
+ * Converts HTML attribute values into the values the engine expects. Every element's
+ * `attributeChangedCallback` funnels through this module.
+ *
+ * The parsers share one contract:
+ *
+ * - A `null` value means the attribute is absent or was removed, and yields the supplied default.
+ * - A malformed value yields the same default and logs exactly one `console.warn` naming the
+ *   attribute, so misuse is reported rather than thrown — nothing here throws or rejects.
+ * - A math-type default is cloned on the way out, which is what makes it safe to pass the engine's
+ *   shared frozen constants (`Vec3.ZERO`, `Color.WHITE`) as defaults.
+ * - `parseBool` and `parseTags` take no attribute name, because every value is valid for them and
+ *   so they never warn.
+ *
+ * `getEntity` is the exception: it resolves a reference to a live entity rather than parsing a
+ * literal, and returns `null` instead of falling back to a default.
+ */
+
+import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
+
+import { CSS_COLORS } from './colors';
+
+/**
+ * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
+ * value does not consist of exactly `count` whitespace-separated finite numbers.
+ *
+ * @param value - The value to split.
+ * @param count - The required number of components.
+ * @returns The parsed components, or `null`.
+ * @ignore
+ */
+export const parseComponents = (value: string, count: number): number[] | null => {
+    const components = value.trim().split(/\s+/).map(Number);
+    if (components.length !== count || components.some(component => !Number.isFinite(component))) {
+        return null;
+    }
+    return components;
+};
+
+/**
+ * Clones a math-type default so parsed results never alias the caller's default instance. This
+ * is what makes it safe to pass the engine's shared frozen constants (e.g. `Vec3.ZERO`,
+ * `Color.WHITE`) as defaults.
+ *
+ * @param value - The default value to clone (`null` is passed through).
+ * @returns The cloned value.
+ */
+const cloneDefault = <T extends Color | Quat | Vec2 | Vec3 | Vec4 | null>(value: T): T => {
+    return (value === null ? null : value.clone()) as T;
+};
+
+/**
+ * Parse a boolean attribute value. The same rules apply to every boolean attribute:
+ *
+ * - Attribute absent (or removed): the supplied default is used.
+ * - Attribute set to the string 'false': `false`.
+ * - Attribute present with any other value, including the empty string of a bare boolean
+ *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed boolean.
+ */
+export const parseBool = (value: string | null, defaultValue: boolean): boolean => {
+    return value === null ? defaultValue : value !== 'false';
+};
+
+/**
+ * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
+ * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
+ * (e.g. '1 0.5 0.5' or '1 0.5 0.5 0.5'). Returns `defaultValue` (cloned, when it is a color)
+ * when the attribute is absent (`null`), or when the value is malformed — the latter also logs
+ * a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Color object.
+ */
+export const parseColor = <T extends Color | null>(value: string | null, defaultValue: T, attribute: string): Color | T => {
+    if (value === null) {
+        return cloneDefault(defaultValue);
+    }
+
+    // A CSS color name (e.g. 'rebeccapurple')
+    const hexColor = CSS_COLORS[value.toLowerCase()];
+    if (hexColor) {
+        return new Color().fromString(hexColor);
+    }
+
+    // A hex color (e.g. '#ff0000'), expanding short forms (e.g. '#f00') for Color.fromString
+    if (/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
+        let hex = value.slice(1);
+        if (hex.length === 3 || hex.length === 4) {
+            hex = hex.split('').map(char => char + char).join('');
+        }
+        return new Color().fromString(`#${hex}`);
+    }
+
+    // 3 or 4 space-separated components (e.g. '1 0.5 0.5')
+    const components = parseComponents(value, 4) ?? parseComponents(value, 3);
+    if (components) {
+        return new Color(components);
+    }
+
+    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a CSS color name, a hex color or 3 or 4 space-separated numbers. Using '${defaultValue}'.`);
+    return cloneDefault(defaultValue);
+};
+
+/**
+ * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+ * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+ * the value is invalid — the latter also logs a warning listing the valid names.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The resolved enum name.
+ */
+export const parseEnum = <T extends string>(
+    value: string | null,
+    valid: readonly T[] | ReadonlyMap<T, number>,
+    defaultValue: T,
+    attribute: string
+): T => {
+    if (value === null) {
+        return defaultValue;
+    }
+    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
+    if (names.includes(value as T)) {
+        return value as T;
+    }
+    console.warn(`Invalid value '${value}' for attribute '${attribute}'. Valid values: ${names.join(', ')}. Using '${defaultValue}'.`);
+    return defaultValue;
+};
+
+/**
+ * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+ * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+ * finite number — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed number.
+ */
+export const parseNumber = <T extends number | null>(value: string | null, defaultValue: T, attribute: string): number | T => {
+    if (value === null) {
+        return defaultValue;
+    }
+    const number = value.trim() === '' ? NaN : Number(value);
+    if (!Number.isFinite(number)) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected a finite number. Using '${defaultValue}'.`);
+        return defaultValue;
+    }
+    return number;
+};
+
+/**
+ * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
+ * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
+ * a quaternion) when the attribute is absent (`null`), or when the value is malformed — the
+ * latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Quat object.
+ */
+export const parseQuat = <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string): Quat | T => {
+    if (value === null) {
+        return cloneDefault(defaultValue);
+    }
+    const components = parseComponents(value, 3);
+    if (!components) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        return cloneDefault(defaultValue);
+    }
+    return new Quat().setFromEulerAngles(components[0], components[1], components[2]);
+};
+
+/**
+ * Parse a tags attribute value. The expected format is a comma-separated list of tag names
+ * (e.g. 'enemy, flying'). Surrounding whitespace is trimmed from each name and empty names are
+ * discarded, so a trailing comma or a doubled separator does not produce a blank tag. Returns a
+ * copy of `defaultValue` when the attribute is absent or removed (`null`).
+ *
+ * Every value is valid, so this never warns.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed tag names.
+ */
+export const parseTags = (value: string | null, defaultValue: string[] = []): string[] => {
+    if (value === null) {
+        // Copied for the same reason cloneDefault exists: a parsed result must never alias the
+        // caller's default, or a later mutation would write back through it.
+        return [...defaultValue];
+    }
+    return value.split(',').map(tag => tag.trim()).filter(tag => tag !== '');
+};
+
+/**
+ * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec2 object.
+ */
+export const parseVec2 = <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string): Vec2 | T => {
+    if (value === null) {
+        return cloneDefault(defaultValue);
+    }
+    const components = parseComponents(value, 2);
+    if (!components) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 2 space-separated numbers. Using '${defaultValue}'.`);
+        return cloneDefault(defaultValue);
+    }
+    return new Vec2(components);
+};
+
+/**
+ * Parse a Vec3 attribute value. The expected format is 3 space-separated numbers (e.g. '1 2 3').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec3 object.
+ */
+export const parseVec3 = <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string): Vec3 | T => {
+    if (value === null) {
+        return cloneDefault(defaultValue);
+    }
+    const components = parseComponents(value, 3);
+    if (!components) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 3 space-separated numbers. Using '${defaultValue}'.`);
+        return cloneDefault(defaultValue);
+    }
+    return new Vec3(components);
+};
+
+/**
+ * Parse a Vec4 attribute value. The expected format is 4 space-separated numbers
+ * (e.g. '1 2 3 4'). Returns `defaultValue` (cloned, when it is a vector) when the attribute is
+ * absent (`null`), or when the value is malformed — the latter also logs a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed Vec4 object.
+ */
+export const parseVec4 = <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string): Vec4 | T => {
+    if (value === null) {
+        return cloneDefault(defaultValue);
+    }
+    const components = parseComponents(value, 4);
+    if (!components) {
+        console.warn(`Invalid value '${value}' for attribute '${attribute}'. Expected 4 space-separated numbers. Using '${defaultValue}'.`);
+        return cloneDefault(defaultValue);
+    }
+    return new Vec4(components);
+};
+
+/**
+ * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
+ * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
+ * entity name. Returns `null` if no matching element (or backing entity) is found.
+ *
+ * @param ref - The reference string to resolve.
+ * @returns The resolved entity, or `null`.
+ */
+export const getEntity = (ref: string): Entity | null => {
+    if (!ref) {
+        return null;
+    }
+
+    let element: Element | null = null;
+
+    // Try the reference as a CSS selector. An invalid selector (e.g. a bare name containing
+    // spaces) throws, in which case we fall back to id/name lookups below.
+    try {
+        element = document.querySelector(ref);
+    } catch {
+        element = null;
+    }
+
+    if (!element) {
+        element = document.getElementById(ref) ?? document.querySelector(`pc-entity[name="${ref}"]`);
+    }
+
+    return (element as { entity?: Entity } | null)?.entity ?? null;
+};

package/src/scene.ts

@@ -2,7 +2,7 @@ import { Color, Scene, Vec3 } from 'playcanvas';
 
 import { AppElement } from './app';
 import { AsyncElement } from './async-element';
-import { parseColor, parseVec3 } from './utils';
+import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
 
 /**
  * The SceneElement interface provides properties and methods for manipulating
@@ -14,7 +14,7 @@ class SceneElement extends AsyncElement {
     /**
      * The fog type of the scene.
      */
-    private _fog = 'none'; // possible values: 'none', 'linear', 'exp', 'exp2'
+    private _fog: 'none' | 'linear' | 'exp' | 'exp2' = 'none';
 
     /**
      * The color of the fog.
@@ -41,15 +41,21 @@ class SceneElement extends AsyncElement {
      */
     private _gravity = new Vec3(0, -9.81, 0);
 
+    private _scene: Scene | null = null;
+
     /**
-     * The PlayCanvas scene instance.
+     * The PlayCanvas scene instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The scene instance.
      */
-    scene: Scene | null = null;
+    get scene(): Scene {
+        return this._scene!;
+    }
 
     async connectedCallback() {
         await this.closestApp?.ready();
 
-        this.scene = this.closestApp!.app!.scene;
+        this._scene = this.closestApp!.app!.scene;
         this.updateSceneSettings();
 
         this._onReady();
@@ -69,7 +75,8 @@ class SceneElement extends AsyncElement {
     }
 
     /**
-     * Sets the fog type of the scene.
+     * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
+     * `none`.
      * @param value - The fog type.
      */
     set fog(value) {
@@ -187,25 +194,25 @@ class SceneElement extends AsyncElement {
         return ['fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'fog':
-                this.fog = newValue;
+                this.fog = parseEnum(newValue, ['none', 'linear', 'exp', 'exp2'], 'none', name);
                 break;
             case 'fog-color':
-                this.fogColor = parseColor(newValue);
+                this.fogColor = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'fog-density':
-                this.fogDensity = parseFloat(newValue);
+                this.fogDensity = parseNumber(newValue, 0, name);
                 break;
             case 'fog-start':
-                this.fogStart = parseFloat(newValue);
+                this.fogStart = parseNumber(newValue, 0, name);
                 break;
             case 'fog-end':
-                this.fogEnd = parseFloat(newValue);
+                this.fogEnd = parseNumber(newValue, 1000, name);
                 break;
             case 'gravity':
-                this.gravity = parseVec3(newValue);
+                this.gravity = parseVec3(newValue, new Vec3(0, -9.81, 0), name);
                 break;
             // ... handle other attributes as well
         }
@@ -214,4 +221,10 @@ class SceneElement extends AsyncElement {
 
 customElements.define('pc-scene', SceneElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scene': SceneElement;
+    }
+}
+
 export { SceneElement };

package/src/sky.ts

@@ -1,8 +1,9 @@
 import { Asset, EnvLighting, LAYERID_SKYBOX, Quat, Scene, Texture, Vec3 } from 'playcanvas';
 
+import { AppElement } from './app';
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
-import { parseVec3 } from './utils';
+import { parseBool, parseEnum, parseNumber, parseVec3 } from './parse';
 
 /**
  * The SkyElement interface provides properties and methods for manipulating
@@ -28,6 +29,8 @@ class SkyElement extends AsyncElement {
 
     private _scene: Scene | null = null;
 
+    private _appElement: AppElement | null = null;
+
     connectedCallback() {
         this._loadSkybox();
         this._onReady();
@@ -35,6 +38,7 @@ class SkyElement extends AsyncElement {
 
     disconnectedCallback() {
         this._unloadSkybox();
+        this._appElement = null;
     }
 
     private _generateSkybox(asset: Asset) {
@@ -67,10 +71,12 @@ class SkyElement extends AsyncElement {
     private async _loadSkybox() {
         const appElement = await this.closestApp?.ready();
         const app = appElement?.app;
-        if (!app) {
+        if (!appElement || !app) {
             return;
         }
 
+        this._appElement = appElement;
+
         const asset = AssetElement.get(this._asset);
         if (!asset) {
             return;
@@ -89,16 +95,22 @@ class SkyElement extends AsyncElement {
     }
 
     private _unloadSkybox() {
-        if (!this._scene) return;
+        const scene = this._scene;
+        if (!scene) return;
+
+        this._scene = null;
+
+        // If the owning application has already been destroyed (removing a <pc-app>
+        // disconnects it before its children), the scene, graphics device and skybox
+        // textures have all been destroyed along with it — nothing left to clean up.
+        if (!this._appElement?.app) return;
 
-        this._scene.skybox?.destroy();
+        scene.skybox?.destroy();
         // @ts-ignore
-        this._scene.skybox = null;
-        this._scene.envAtlas?.destroy();
+        scene.skybox = null;
+        scene.envAtlas?.destroy();
         // @ts-ignore
-        this._scene.envAtlas = null;
-
-        this._scene = null;
+        scene.envAtlas = null;
     }
 
     /**
@@ -258,31 +270,31 @@ class SkyElement extends AsyncElement {
         return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
             case 'asset':
-                this.asset = newValue;
+                this.asset = newValue ?? '';
                 break;
             case 'center':
-                this.center = parseVec3(newValue);
+                this.center = parseVec3(newValue, new Vec3(0, 0.01, 0), name);
                 break;
             case 'intensity':
-                this.intensity = parseFloat(newValue);
+                this.intensity = parseNumber(newValue, 1, name);
                 break;
             case 'level':
-                this.level = parseInt(newValue, 10);
+                this.level = parseNumber(newValue, 0, name);
                 break;
             case 'lighting':
-                this.lighting = this.hasAttribute(name);
+                this.lighting = parseBool(newValue, false);
                 break;
             case 'rotation':
-                this.rotation = parseVec3(newValue);
+                this.rotation = parseVec3(newValue, Vec3.ZERO, name);
                 break;
             case 'scale':
-                this.scale = parseVec3(newValue);
+                this.scale = parseVec3(newValue, new Vec3(100, 100, 100), name);
                 break;
             case 'type':
-                this.type = newValue as 'box' | 'dome' | 'infinite' | 'none';
+                this.type = parseEnum(newValue, ['box', 'dome', 'infinite', 'none'], 'infinite', name);
                 break;
         }
     }
@@ -290,4 +302,10 @@ class SkyElement extends AsyncElement {
 
 customElements.define('pc-sky', SkyElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sky': SkyElement;
+    }
+}
+
 export { SkyElement };

package/dist/utils.d.ts

@@ -1,56 +0,0 @@
-import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
-/**
- * Parse a color string into a Color object. String can be in the format of '#rgb', '#rgba',
- * '#rrggbb', '#rrggbbaa', or a string of 3 or 4 comma-delimited numbers.
- *
- * @param value - The color string to parse.
- * @returns The parsed Color object.
- */
-export declare const parseColor: (value: string) => Color;
-/**
- * Parse an Euler angles string into a Quat object. String can be in the format of 'x,y,z'.
- *
- * @param value - The Euler angles string to parse.
- * @returns The parsed Quat object.
- */
-export declare const parseQuat: (value: string) => Quat;
-/**
- * Parse a Vec2 string into a Vec2 object. String can be in the format of 'x,y'.
- *
- * @param value - The Vec2 string to parse.
- * @returns The parsed Vec2 object.
- */
-export declare const parseVec2: (value: string) => Vec2;
-/**
- * Parse a Vec3 string into a Vec3 object. String can be in the format of 'x,y,z'.
- *
- * @param value - The Vec3 string to parse.
- * @returns The parsed Vec3 object.
- */
-export declare const parseVec3: (value: string) => Vec3;
-/**
- * Parse a Vec4 string into a Vec4 object. String can be in the format of 'x,y,z,w'.
- *
- * @param value - The Vec4 string to parse.
- * @returns The parsed Vec4 object.
- */
-export declare const parseVec4: (value: string) => Vec4;
-/**
- * Resolves an enum value supplied as either a named string (looked up in `map`) or a numeric
- * string. Falls back to `defaultValue` when the value is neither a known name nor a finite number.
- *
- * @param value - The attribute value to parse.
- * @param map - A map of named values to their numeric enum equivalents.
- * @param defaultValue - The value to return when parsing fails.
- * @returns The resolved numeric enum value.
- */
-export declare const parseEnum: (value: string, map: Map<string, number>, defaultValue: number) => number;
-/**
- * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
- * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare
- * entity name. Returns `null` if no matching element (or backing entity) is found.
- *
- * @param ref - The reference string to resolve.
- * @returns The resolved entity, or `null`.
- */
-export declare const getEntity: (ref: string) => Entity | null;