@playcanvas/web-components 0.13.1 → 0.14.0

package/dist/pwc.js

@@ -186,6 +186,7 @@
      * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
      * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
      * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+     * @internal
      */
     class LoadingBar {
         _track;
@@ -284,6 +285,11 @@
         }
     }
 
+    /**
+     * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+     * names as attribute values.
+     * @internal
+     */
     const CSS_COLORS = {
         aliceblue: '#f0f8ff',
         antiquewhite: '#faebd7',
@@ -459,7 +465,7 @@
      * @param value - The value to split.
      * @param count - The required number of components.
      * @returns The parsed components, or `null`.
-     * @ignore
+     * @internal
      */
     const parseComponents = (value, count) => {
         const components = value.trim().split(/\s+/).map(Number);
@@ -490,6 +496,7 @@
      * @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.
+     * @internal
      */
     const parseBool = (value, defaultValue) => {
         return value === null ? defaultValue : value !== 'false';
@@ -505,6 +512,7 @@
      * @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.
+     * @internal
      */
     const parseColor = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -546,6 +554,7 @@
      * @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.
+     * @internal
      */
     const parseEnum = (value, valid, defaultValue, attribute) => {
         if (value === null) {
@@ -567,6 +576,7 @@
      * @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.
+     * @internal
      */
     const parseNumber = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -589,6 +599,7 @@
      * @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.
+     * @internal
      */
     const parseQuat = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -612,6 +623,7 @@
      * @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.
+     * @internal
      */
     const parseTags = (value, defaultValue = []) => {
         if (value === null) {
@@ -633,6 +645,7 @@
      * @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.
+     * @internal
      */
     const parseVec2 = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -654,6 +667,7 @@
      * @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.
+     * @internal
      */
     const parseVec3 = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -675,6 +689,7 @@
      * @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.
+     * @internal
      */
     const parseVec4 = (value, defaultValue, attribute) => {
         if (value === null) {
@@ -694,6 +709,7 @@
      *
      * @param ref - The reference string to resolve.
      * @returns The resolved entity, or `null`.
+     * @internal
      */
     const getEntity = (ref) => {
         if (!ref) {
@@ -1598,7 +1614,7 @@
     /**
      * The attribute names of the inline `onpointer*` event handlers, shared by every element that
      * fronts an engine entity. Spread into `observedAttributes` by subclasses.
-     * @ignore
+     * @internal
      */
     const POINTER_ATTRIBUTES = [
         'onpointerenter',
@@ -6059,6 +6075,7 @@
         _metalnessMapRotation = 0;
         _metalnessMapTiling = new playcanvas.Vec2(1, 1);
         _metalnessMapUv = 0;
+        _name = 'Untitled';
         _normalMap = '';
         _normalMapOffset = new playcanvas.Vec2(0, 0);
         _normalMapRotation = 0;
@@ -6176,6 +6193,7 @@
             material.metalnessMapRotation = this._metalnessMapRotation;
             material.metalnessMapTiling = this._metalnessMapTiling;
             material.metalnessMapUv = this._metalnessMapUv;
+            material.name = this._name;
             material.normalMapOffset = this._normalMapOffset;
             material.normalMapRotation = this._normalMapRotation;
             material.normalMapTiling = this._normalMapTiling;
@@ -7262,6 +7280,26 @@
         get metalnessMapUv() {
             return this._metalnessMapUv;
         }
+        /**
+         * Sets the name of the material.
+         * @param value - The material name.
+         */
+        set name(value) {
+            this._name = value;
+            if (this.material) {
+                // A label rather than shader state, so no update() is scheduled
+                this.material.name = value;
+            }
+        }
+        /**
+         * Gets the name of the material - the label shown wherever materials surface by name, such
+         * as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a
+         * label: element references resolve through `id`.
+         * @returns The material name.
+         */
+        get name() {
+            return this._name;
+        }
         /**
          * Sets the id of the `pc-asset` to use as the normal map.
          * @param value - The asset id.
@@ -7833,6 +7871,7 @@
                 'metalness-map-rotation',
                 'metalness-map-tiling',
                 'metalness-map-uv',
+                'name',
                 'normal-map',
                 'normal-map-offset',
                 'normal-map-rotation',
@@ -8033,6 +8072,9 @@
                 case 'metalness-map-uv':
                     this.metalnessMapUv = parseNumber(newValue, 0, name);
                     break;
+                case 'name':
+                    this.name = newValue ?? 'Untitled';
+                    break;
                 case 'normal-map':
                     this.normalMap = newValue ?? '';
                     break;
@@ -10578,6 +10620,41 @@
     }
     customElements.define('pc-gsplat', GSplatComponentElement);
 
+    /**
+     * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
+     * name is shared by several nodes in the model, the attached component types, and the material
+     * names of a render component.
+     *
+     * @param node - The node to format.
+     * @param counts - The number of nodes bearing each name.
+     * @returns The formatted line.
+     */
+    const formatNode = (node, counts) => {
+        const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
+        const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
+        // Braces rather than brackets: `[N]` already means a match index on this line
+        const materials = node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
+        return `${node.name}${index}${components}${materials}`;
+    };
+    /**
+     * Formats the printable form of a hierarchy subtree.
+     *
+     * @param root - The subtree root.
+     * @param counts - The number of nodes bearing each name.
+     * @returns The tree, one line per node.
+     */
+    const formatHierarchy = (root, counts) => {
+        const lines = [formatNode(root, counts)];
+        const walk = (node, prefix) => {
+            node.children.forEach((child, i) => {
+                const last = i === node.children.length - 1;
+                lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
+                walk(child, `${prefix}${last ? '   ' : '│  '}`);
+            });
+        };
+        walk(root, '');
+        return lines.join('\n');
+    };
     /**
      * The ModelElement interface provides properties and methods for manipulating
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
@@ -10624,6 +10701,57 @@
         get entity() {
             return this._entity;
         }
+        /**
+         * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
+         * container asset has not loaded, or the element has left the document). One call grounds a
+         * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
+         * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
+         * indices, attached component types and the material assignments of render components
+         * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
+         * is the printable form.
+         *
+         * The snapshot is plain data, computed afresh each call: it does not follow later changes
+         * to the hierarchy, and mutating it changes nothing.
+         *
+         * @returns The root of the instantiated node tree, or `null`.
+         */
+        hierarchy() {
+            const root = this._entity;
+            if (!root) {
+                return null;
+            }
+            // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
+            // from the model root, the root itself included — so each node's index is exactly what
+            // a pc-node's index attribute selects. Once the walk completes, the map holds the total
+            // count per name, which is what the printable form reads to annotate only shared names.
+            const ordinals = new Map();
+            const describe = (entity, pathBelowRoot) => {
+                const index = ordinals.get(entity.name) ?? 0;
+                ordinals.set(entity.name, index + 1);
+                const node = {
+                    name: entity.name,
+                    // The root has no path below itself; its own name stands in, as it does for
+                    // the path a pc-node bound to the root reports.
+                    path: pathBelowRoot || entity.name,
+                    index,
+                    // A plain GraphNode grafted into the hierarchy has no component storage
+                    components: Object.keys(entity.c ?? {}).sort(),
+                    materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
+                        index: slot,
+                        name: meshInstance.material?.name ?? null
+                    })),
+                    children: entity.children.map((child) => describe(child, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name))
+                };
+                // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
+                // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
+                Object.defineProperty(node, 'toString', {
+                    enumerable: false,
+                    value: () => formatHierarchy(node, ordinals)
+                });
+                return node;
+            };
+            return describe(root, '');
+        }
         connectedCallback() {
             // A model outside an application is inert and never becomes ready, so awaiting it hangs.
             // Warn rather than fail silently, naming the parent it requires, as every other misplaced
@@ -10782,6 +10910,74 @@
     }
     customElements.define('pc-model', ModelElement);
 
+    /**
+     * Parses one mapping into its valid rules, warning for each entry that is not one: an unknown
+     * or missing selector prefix, an empty `name:` value, an `index:` value that is not a
+     * non-negative integer, or a replacement id that is not a non-empty string. An invalid rule
+     * behaves exactly as if absent from the mapping.
+     *
+     * @param overrides - The mapping to parse.
+     * @param label - The element description for warnings.
+     * @returns The valid rules.
+     */
+    const parseMaterialRules = (overrides, label) => {
+        const rules = [];
+        for (const [selector, id] of Object.entries(overrides)) {
+            if (typeof id !== 'string' || id === '') {
+                console.warn(`${label} material-overrides '${selector}' needs a pc-material id - rule ignored`);
+            }
+            else if (selector.startsWith('name:')) {
+                // The text after the prefix is the selector value, exactly as written - a material
+                // name may legitimately begin or end with whitespace
+                const name = selector.slice('name:'.length);
+                if (name === '') {
+                    console.warn(`${label} material-overrides 'name:' selector is empty - rule ignored`);
+                }
+                else {
+                    rules.push({ kind: 'name', name, id });
+                }
+            }
+            else if (selector.startsWith('index:')) {
+                // Whitespace around the number is tolerated; Number('') is 0, so blank means NaN
+                const text = selector.slice('index:'.length).trim();
+                const index = text === '' ? NaN : Number(text);
+                if (!Number.isInteger(index) || index < 0) {
+                    console.warn(`${label} material-overrides '${selector}' is not a non-negative integer index - rule ignored`);
+                }
+                else {
+                    rules.push({ kind: 'index', index, id });
+                }
+            }
+            else {
+                console.warn(`${label} material-overrides '${selector}' has no 'name:' or 'index:' prefix - rule ignored`);
+            }
+        }
+        return rules;
+    };
+    /**
+     * Parses the material-overrides attribute text. Anything but a JSON object — malformed JSON, an
+     * array, a primitive — warns and yields `null`, the absent mapping: a stale mapping must not
+     * survive an attribute value the DOM no longer represents.
+     *
+     * @param text - The attribute text.
+     * @param label - The element description for warnings.
+     * @returns The mapping, or `null`.
+     */
+    const parseMaterialOverridesAttribute = (text, label) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            console.warn(`${label} material-overrides is not valid JSON - treated as absent: ${error.message}`);
+            return null;
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            console.warn(`${label} material-overrides must be a JSON object - treated as absent`);
+            return null;
+        }
+        return parsed;
+    };
     /**
      * Computes the Levenshtein distance between two strings, for near-miss suggestions in the
      * resolution warnings.
@@ -10837,6 +11033,13 @@
      * "x y z" triple.
      * @attribute {string} scale - Overrides the node's local scale, as an "x y z" triple.
      * @attribute {string} tags - Overrides the node's tags, separated by spaces or commas.
+     * @attribute {string} material-overrides - Overrides material assignments on the bound node's
+     * render component, as a JSON object from selector to `pc-material` id — for example
+     * `{"name:CarPaint": "candy-red", "index:7": "smoked-glass"}`. A `name:X` key selects every mesh
+     * instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and
+     * wins over a name rule for the same instance. Assignments no rule matches keep their baseline
+     * materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to
+     * discover the names and indices a node offers.
      * @attribute {string} onpointerenter - Script to run when the pointer moves onto the node.
      * @attribute {string} onpointerleave - Script to run when the pointer moves off the node.
      * @attribute {string} onpointermove - Script to run when the pointer moves over the node.
@@ -10872,12 +11075,25 @@
         _destroyHandle = null;
         /** The authored values displaced by this element's overrides, captured per property. */
         _authored = {};
+        /**
+         * The model-authored render component of the bound node, recorded at bind — before child
+         * decorations build — so a render component added later by a child `pc-render` can never
+         * become the override target. `null` when the bound node has none.
+         */
+        _authoredRender = null;
+        /**
+         * The baseline assignments displaced by the material overrides, captured for every mesh
+         * instance when the first non-empty mapping applies and released when the mapping goes
+         * absent (restoring them) or the binding dissolves.
+         */
+        _baseline = null;
         // Override values. `null` means "no override": the authored value stays in force.
         _enabled = null;
         _position = null;
         _rotation = null;
         _scale = null;
         _tags = null;
+        _materialOverrides = null;
         /**
          * The binding state: `pending` until the host instantiates and `name` resolves, `bound`
          * once decorated, `missing`/`ambiguous`/`duplicate` when resolution failed (each also
@@ -11011,6 +11227,7 @@
             this._destroyHandle = target.once('destroy', this._onEntityDestroy, this);
             this._state = 'bound';
             this._path = this._pathOf(target, hostEntity);
+            this._authoredRender = target.render ?? null;
             this._applyOverrides();
             this._onReady();
             this._buildChildren();
@@ -11041,6 +11258,7 @@
             this._entity = null;
             this._path = null;
             this._authored = {};
+            this._authoredRender = null;
             // Component decorations come off through the same hook the host-ready cycle uses. A
             // dissolve that never rebinds fires no ready event, so the sweep is explicit - after
             // `_entity` is cleared, so the hook sees a host without an entity.
@@ -11062,6 +11280,9 @@
             this._entity = null;
             this._path = null;
             this._authored = {};
+            this._authoredRender = null;
+            // The mesh instances died with the entity - the capture is dropped, not restored
+            this._baseline = null;
             this._state = 'pending';
             this._resetReady();
         }
@@ -11103,6 +11324,9 @@
             if (this._tags !== null) {
                 this.tags = this._tags;
             }
+            if (this._materialOverrides !== null) {
+                this._applyMaterialOverrides();
+            }
         }
         /**
          * Restores every authored value this element's overrides displaced. The override values
@@ -11128,6 +11352,104 @@
                 entity.tags.add(authored.tags);
             }
             this._authored = {};
+            this._restoreBaseline();
+        }
+        /**
+         * Applies the material mapping to the authored render component: parse the mapping's valid
+         * rules, capture the baseline on first application, then recompute every assignment from
+         * that baseline - name rules write over it, index rules write over them, so `index:` wins -
+         * and assign whatever changed. An absent mapping, or one with no valid rules, restores the
+         * baseline instead. Called while bound, from `_applyOverrides` and the property setter.
+         */
+        _applyMaterialOverrides() {
+            const label = `pc-node '${this._name}'`;
+            const rules = this._materialOverrides ? parseMaterialRules(this._materialOverrides, label) : [];
+            if (rules.length === 0) {
+                this._restoreBaseline();
+                return;
+            }
+            if (!this._baseline) {
+                if (!this._authoredRender) {
+                    console.warn(`${label} is bound to a node without an authored render component - material-overrides ignored`);
+                    return;
+                }
+                this._baseline = this._authoredRender.meshInstances.map((meshInstance) => ({
+                    meshInstance,
+                    material: meshInstance.material ?? null,
+                    name: meshInstance.material?.name ?? null
+                }));
+            }
+            const baseline = this._baseline;
+            /** Resolves a replacement id, warning when it does not resolve. */
+            const resolveReplacement = (id) => {
+                const material = MaterialElement.get(id);
+                if (!material) {
+                    console.warn(`${label} material-overrides could not resolve pc-material '${id}' - rule ignored`);
+                }
+                return material ?? null;
+            };
+            // Recompute the whole list from the baseline: name rules write over it, index rules
+            // write over them. Recomputing makes mapping edits order-independent, and a rule whose
+            // replacement does not resolve simply leaves the layer below it in force.
+            const resolved = baseline.map((assignment) => assignment.material);
+            for (const rule of rules) {
+                if (rule.kind !== 'name') {
+                    continue;
+                }
+                const material = resolveReplacement(rule.id);
+                if (!material) {
+                    continue;
+                }
+                let matched = false;
+                baseline.forEach((assignment, index) => {
+                    if (assignment.name === rule.name) {
+                        resolved[index] = material;
+                        matched = true;
+                    }
+                });
+                if (!matched) {
+                    const names = baseline.map((assignment) => `'${assignment.name}'`).join(', ');
+                    console.warn(`${label} material-overrides 'name:${rule.name}' matches no assignment - ` +
+                        `baseline names: ${names || '(none)'}`);
+                }
+            }
+            for (const rule of rules) {
+                if (rule.kind !== 'index') {
+                    continue;
+                }
+                if (rule.index >= baseline.length) {
+                    console.warn(`${label} material-overrides 'index:${rule.index}' is out of range - ` +
+                        `${baseline.length} assignment(s)`);
+                    continue;
+                }
+                const material = resolveReplacement(rule.id);
+                if (material) {
+                    resolved[rule.index] = material;
+                }
+            }
+            baseline.forEach((assignment, index) => {
+                // The engine setter rebuilds material and shader state even for a redundant write,
+                // so only actual changes are assigned
+                if (assignment.meshInstance.material !== resolved[index]) {
+                    assignment.meshInstance.material = resolved[index];
+                }
+            });
+        }
+        /**
+         * Restores every baseline assignment the material overrides displaced and releases the
+         * capture, so the next non-empty mapping captures afresh. Safe to call without a capture.
+         */
+        _restoreBaseline() {
+            const baseline = this._baseline;
+            if (!baseline) {
+                return;
+            }
+            this._baseline = null;
+            for (const assignment of baseline) {
+                if (assignment.meshInstance.material !== assignment.material) {
+                    assignment.meshInstance.material = assignment.material;
+                }
+            }
         }
         /**
          * Renders the path of `node` below `root`, for the `path` property and the resolution
@@ -11348,8 +11670,41 @@
         get tags() {
             return this._tags;
         }
+        /**
+         * Sets the material overrides: a sparse mapping from selector to `pc-material` id, applied
+         * to the bound node's authored render component. A `name:X` key selects every mesh instance
+         * whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins
+         * over a name rule for the same instance. Assignments no rule matches keep their baseline
+         * materials. `null` clears the mapping, restoring every baseline assignment.
+         * @param value - The mapping, or `null`.
+         */
+        set materialOverrides(value) {
+            // Copied and frozen: later caller mutation of the passed object must not silently
+            // disagree with the mapping the element applied
+            this._materialOverrides = value === null ? null : Object.freeze({ ...value });
+            if (this._state === 'bound') {
+                this._applyMaterialOverrides();
+            }
+        }
+        /**
+         * Gets the material overrides.
+         * @returns The mapping, or `null` while no override is set.
+         */
+        get materialOverrides() {
+            return this._materialOverrides;
+        }
         static get observedAttributes() {
-            return ['enabled', 'index', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+            return [
+                'enabled',
+                'index',
+                'material-overrides',
+                'name',
+                'position',
+                'rotation',
+                'scale',
+                'tags',
+                ...POINTER_ATTRIBUTES
+            ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -11374,6 +11729,10 @@
                         }
                     }
                     break;
+                case 'material-overrides':
+                    this.materialOverrides =
+                        newValue === null ? null : parseMaterialOverridesAttribute(newValue, `pc-node '${this._name}'`);
+                    break;
                 case 'name':
                     this.name = newValue ?? '';
                     break;