@needle-tools/engine 4.17.0-next.36dcae2 → 4.17.0-next.4989636

package/src/engine/js-extensions/Object3D.ts

@@ -185,207 +185,211 @@ export function apply(object: Object3D) {
     }
 }
 
-if (NEEDLE_ENGINE_FEATURE_FLAGS.experimentalSmartHierarchyUpdate) {
+let initialized = false;
 
-    const addFn = Object3D.prototype.add;
-    Object3D.prototype.add = function (...args: any) {
-        markHierarchyDirty();
-        return addFn.apply(this, args);
-    }
-
-    const attachFn = Object3D.prototype.attach;
-    Object3D.prototype.attach = function (...args: any) {
-        markHierarchyDirty();
-        return attachFn.apply(this, args);
-    }
+export function initObject3DExtensions() {
+    if (initialized) return;
+    initialized = true;
 
-    const removeFn = Object3D.prototype.remove;
-    Object3D.prototype.remove = function (...args: any) {
-        markHierarchyDirty();
-        return removeFn.apply(this, args);
-    }
-}
+    if (NEEDLE_ENGINE_FEATURE_FLAGS.experimentalSmartHierarchyUpdate) {
 
-// #region Prototype Method Implementations
-
-Object3D.prototype["SetActive"] = function (active: boolean) {
-    this.visible = active;
-}
-// e.g. when called via a UnityEvent
-Object3D.prototype["setActive"] = function (active: boolean) {
-    this.visible = active;
-}
+        const addFn = Object3D.prototype.add;
+        Object3D.prototype.add = function (...args: any) {
+            markHierarchyDirty();
+            return addFn.apply(this, args);
+        }
 
-Object3D.prototype["destroy"] = function () {
-    destroy(this);
-}
+        const attachFn = Object3D.prototype.attach;
+        Object3D.prototype.attach = function (...args: any) {
+            markHierarchyDirty();
+            return attachFn.apply(this, args);
+        }
 
-Object3D.prototype["addComponent"] = function <T extends IComponent>(comp: T | ConstructorConcrete<T>, init?: ComponentInit<T>) {
-    return addComponent(this, comp, init);
-}
+        const removeFn = Object3D.prototype.remove;
+        Object3D.prototype.remove = function (...args: any) {
+            markHierarchyDirty();
+            return removeFn.apply(this, args);
+        }
+    }
 
-Object3D.prototype["addNewComponent"] = function <T extends Component>(type: ConstructorConcrete<T>, init?: ComponentInit<T>) {
-    return addComponent(this, type, init);
-}
+    // #region Prototype Method Implementations
 
-Object3D.prototype["removeComponent"] = function (inst: Component) {
-    return removeComponent(this, inst);
-}
+    Object3D.prototype["SetActive"] = function (active: boolean) {
+        this.visible = active;
+    }
+    // e.g. when called via a UnityEvent
+    Object3D.prototype["setActive"] = function (active: boolean) {
+        this.visible = active;
+    }
 
-Object3D.prototype["getOrAddComponent"] = function <T extends IComponent>(typeName: ConstructorConcrete<T>, init?: ComponentInit<T>): T {
-    return getOrAddComponent<T>(this, typeName, init);
-}
+    Object3D.prototype["destroy"] = function () {
+        destroy(this);
+    }
 
-Object3D.prototype["getComponent"] = function <T extends IComponent>(type: Constructor<T>) {
-    return getComponent(this, type);
-}
+    Object3D.prototype["addComponent"] = function <T extends IComponent>(comp: T | ConstructorConcrete<T>, init?: ComponentInit<T>) {
+        return addComponent(this, comp, init);
+    }
 
-Object3D.prototype["getComponents"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
-    return getComponents(this, type, arr);
-}
+    Object3D.prototype["addNewComponent"] = function <T extends Component>(type: ConstructorConcrete<T>, init?: ComponentInit<T>) {
+        return addComponent(this, type, init);
+    }
 
-Object3D.prototype["getComponentInChildren"] = function <T extends IComponent>(type: Constructor<T>, includeInactive: boolean = false) {
-    return getComponentInChildren(this, type, includeInactive);
-}
+    Object3D.prototype["removeComponent"] = function (inst: Component) {
+        return removeComponent(this, inst);
+    }
 
-Object3D.prototype["getComponentsInChildren"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
-    return getComponentsInChildren(this, type, arr);
-}
+    Object3D.prototype["getOrAddComponent"] = function <T extends IComponent>(typeName: ConstructorConcrete<T>, init?: ComponentInit<T>): T {
+        return getOrAddComponent<T>(this, typeName, init);
+    }
 
-Object3D.prototype["getComponentInParent"] = function <T extends IComponent>(type: Constructor<T>, includeInactive: boolean = false) {
-    return getComponentInParent(this, type, includeInactive);
-}
+    Object3D.prototype["getComponent"] = function <T extends IComponent>(type: Constructor<T>) {
+        return getComponent(this, type);
+    }
 
-Object3D.prototype["getComponentsInParent"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
-    return getComponentsInParent(this, type, arr);
-}
+    Object3D.prototype["getComponents"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
+        return getComponents(this, type, arr);
+    }
 
-// #region Prototype Property Implementations
+    Object3D.prototype["getComponentInChildren"] = function <T extends IComponent>(type: Constructor<T>, includeInactive: boolean = false) {
+        return getComponentInChildren(this, type, includeInactive);
+    }
 
-// this is a fix to allow gameObject active animation be applied to a three object
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "activeSelf")) {
-    Object.defineProperty(Object3D.prototype, "activeSelf", {
-        get: function () {
-            return isActiveSelf(this)
-        },
-        set: function (val: boolean | number) {
-            setActive(this, val);
-        }
-    });
-}
+    Object3D.prototype["getComponentsInChildren"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
+        return getComponentsInChildren(this, type, arr);
+    }
 
+    Object3D.prototype["getComponentInParent"] = function <T extends IComponent>(type: Constructor<T>, includeInactive: boolean = false) {
+        return getComponentInParent(this, type, includeInactive);
+    }
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "raycastAllowed")) {
-    Object.defineProperty(Object3D.prototype, "raycastAllowed", {
-        get: function () {
-            return this.userData && this.userData.raycastAllowed !== false;
-        },
-        set: function (val: boolean) {
-            const self = this as Object3D;
-            if (!self.userData) self.userData = {};
-            self.userData.raycastAllowed = val;
-        }
-    });
-}
+    Object3D.prototype["getComponentsInParent"] = function <T extends IComponent>(type: Constructor<T>, arr?: []) {
+        return getComponentsInParent(this, type, arr);
+    }
 
+    // #region Prototype Property Implementations
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldPosition")) {
-    Object.defineProperty(Object3D.prototype, "worldPosition", {
-        get: function () {
-            // TODO: would be great to remove this - just a workaround because the TransformControlsGizmo also defines this
-            if (this instanceof TransformControlsGizmo) {
-                return getWorldPosition(this["object"]);
+    // this is a fix to allow gameObject active animation be applied to a three object
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "activeSelf")) {
+        Object.defineProperty(Object3D.prototype, "activeSelf", {
+            get: function () {
+                return isActiveSelf(this)
+            },
+            set: function (val: boolean | number) {
+                setActive(this, val);
             }
-            return getWorldPosition(this);
-        },
-        set: function (val: Vector3) {
-            setWorldPosition(this, val)
-        }
-    });
-}
+        });
+    }
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldQuaternion")) {
-    Object.defineProperty(Object3D.prototype, "worldQuaternion", {
-        get: function () {
-            if (this instanceof TransformControlsGizmo) {
-                return getWorldQuaternion(this["object"]);
+
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "raycastAllowed")) {
+        Object.defineProperty(Object3D.prototype, "raycastAllowed", {
+            get: function () {
+                return this.userData && this.userData.raycastAllowed !== false;
+            },
+            set: function (val: boolean) {
+                const self = this as Object3D;
+                if (!self.userData) self.userData = {};
+                self.userData.raycastAllowed = val;
             }
-            return getWorldQuaternion(this);
-        },
-        set: function (val: Quaternion) {
-            setWorldQuaternion(this, val)
-        }
-    });
-}
+        });
+    }
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldRotation")) {
-    Object.defineProperty(Object3D.prototype, "worldRotation", {
-        get: function () {
-            return getWorldRotation(this);
-        },
-        set: function (val: Vector3) {
-            setWorldRotation(this, val)
-        }
-    });
-}
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldScale")) {
-    Object.defineProperty(Object3D.prototype, "worldScale", {
-        get: function () {
-            return getWorldScale(this);
-        },
-        set: function (val: Vector3) {
-            setWorldScale(this, val)
-        }
-    });
-}
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldPosition")) {
+        Object.defineProperty(Object3D.prototype, "worldPosition", {
+            get: function () {
+                // TODO: would be great to remove this - just a workaround because the TransformControlsGizmo also defines this
+                if (this instanceof TransformControlsGizmo) {
+                    return getWorldPosition(this["object"]);
+                }
+                return getWorldPosition(this);
+            },
+            set: function (val: Vector3) {
+                setWorldPosition(this, val)
+            }
+        });
+    }
 
-const tempMatrix = new Matrix4();
-const zero = new Vector3(0, 0, 0);
-const up = new Vector3(0, 1, 0);
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldForward")) {
-    Object.defineProperty(Object3D.prototype, "worldForward", {
-        get: function () {
-            return getTempVector().set(0, 0, 1).applyQuaternion(getWorldQuaternion(this));
-        },
-        set: function (v: Vector3) {
-            const quat = getTempQuaternion().setFromRotationMatrix(tempMatrix.lookAt(zero.set(0, 0, 0), v, up.set(0, 1, 0)));
-            this.worldQuaternion = quat;
-        }
-    });
-}
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldRight")) {
-    Object.defineProperty(Object3D.prototype, "worldRight", {
-        get: function () {
-            return getTempVector().set(1, 0, 0).applyQuaternion(getWorldQuaternion(this));
-        },
-    });
-}
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldUp")) {
-    Object.defineProperty(Object3D.prototype, "worldUp", {
-        get: function () {
-            return getTempVector().set(0, 1, 0).applyQuaternion(getWorldQuaternion(this));
-        },
-    });
-}
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldQuaternion")) {
+        Object.defineProperty(Object3D.prototype, "worldQuaternion", {
+            get: function () {
+                if (this instanceof TransformControlsGizmo) {
+                    return getWorldQuaternion(this["object"]);
+                }
+                return getWorldQuaternion(this);
+            },
+            set: function (val: Quaternion) {
+                setWorldQuaternion(this, val)
+            }
+        });
+    }
 
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldRotation")) {
+        Object.defineProperty(Object3D.prototype, "worldRotation", {
+            get: function () {
+                return getWorldRotation(this);
+            },
+            set: function (val: Vector3) {
+                setWorldRotation(this, val)
+            }
+        });
+    }
 
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldScale")) {
+        Object.defineProperty(Object3D.prototype, "worldScale", {
+            get: function () {
+                return getWorldScale(this);
+            },
+            set: function (val: Vector3) {
+                setWorldScale(this, val)
+            }
+        });
+    }
 
-if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "contains")) {
-    Object.defineProperty(Object3D.prototype, "contains", {
-        value: function (object: Object3D | null | undefined): boolean {
-            if (!object) return false;
-            if (this === object) return true;
-            for (const child of this.children) {
-                if (child.contains(object)) return true;
+    const tempMatrix = new Matrix4();
+    const zero = new Vector3(0, 0, 0);
+    const up = new Vector3(0, 1, 0);
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldForward")) {
+        Object.defineProperty(Object3D.prototype, "worldForward", {
+            get: function () {
+                return getTempVector().set(0, 0, 1).applyQuaternion(getWorldQuaternion(this));
+            },
+            set: function (v: Vector3) {
+                const quat = getTempQuaternion().setFromRotationMatrix(tempMatrix.lookAt(zero.set(0, 0, 0), v, up.set(0, 1, 0)));
+                this.worldQuaternion = quat;
             }
-            return false;
-        }
-    });
-}
+        });
+    }
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldRight")) {
+        Object.defineProperty(Object3D.prototype, "worldRight", {
+            get: function () {
+                return getTempVector().set(1, 0, 0).applyQuaternion(getWorldQuaternion(this));
+            },
+        });
+    }
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldUp")) {
+        Object.defineProperty(Object3D.prototype, "worldUp", {
+            get: function () {
+                return getTempVector().set(0, 1, 0).applyQuaternion(getWorldQuaternion(this));
+            },
+        });
+    }
 
 
 
+    if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "contains")) {
+        Object.defineProperty(Object3D.prototype, "contains", {
+            value: function (object: Object3D | null | undefined): boolean {
+                if (!object) return false;
+                if (this === object) return true;
+                for (const child of this.children) {
+                    if (child.contains(object)) return true;
+                }
+                return false;
+            }
+        });
+    }
 
-// do this after adding the component extensions
-registerPrototypeExtensions(Object3D);
+    // do this after adding the component extensions
+    registerPrototypeExtensions(Object3D);
+}

package/src/engine/js-extensions/Vector.ts

@@ -17,8 +17,15 @@ declare module 'three' {
     }
 }
 
-Vector3.prototype["slerp"] = function (end: Vector3, t: number) {
-    return slerp(this, end, t);
-}
+let initialized = false;
+
+export function initVectorExtensions() {
+    if (initialized) return;
+    initialized = true;
 
-registerPrototypeExtensions(Vector3);
+    Vector3.prototype["slerp"] = function (end: Vector3, t: number) {
+        return slerp(this, end, t);
+    }
+
+    registerPrototypeExtensions(Vector3);
+}

package/src/engine/js-extensions/index.ts

@@ -1,6 +1,3 @@
-import "./Layers.js";
-import "./Camera.js";
 export * from "./ExtensionUtils.js";
 export { apply } from "./Object3D.js";
 export * from "./RGBAColor.js";
-export { } from "./Vector.js";

package/src/engine/webcomponents/WebXRButtons.ts

@@ -1,6 +1,4 @@
-import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.js";
 import { isDevEnvironment, showBalloonMessage } from "../debug/index.js";
-import { findObjectOfType } from "../engine_components.js";
 import { Context } from "../engine_setup.js";
 import { DeviceUtilities } from "../engine_utils.js";
 import { NeedleXRSession } from "../engine_xr.js";
@@ -8,6 +6,7 @@ import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { ButtonsFactory } from "./buttons.js";
 import { getIconElement } from "./icons.js";
 import { NeedleMenu } from "./needle menu/needle-menu.js";
+import { getOrCreateQuicklookHandler,type IQuicklookHandler } from "./quicklook-handler.js";
 
 // TODO: move these buttons into their own web components so their logic is encapsulated (e.g. the CSS animation when a xr session is requested)
 
@@ -76,22 +75,22 @@ export class WebXRButtonFactory {
         NeedleMenu.setElementPriority(button, quicklookButtonPriority);
 
         let createdExporter = false;
-        let usdzExporter: USDZExporter | null = null;
+        let quicklookHandler: IQuicklookHandler | null = null;
         button.addEventListener("click", () => {
-            usdzExporter = findObjectOfType(USDZExporter);
+            const result = getOrCreateQuicklookHandler();
 
-            // if the scene doesnt have an USDZExporter component, create one
-            if (!usdzExporter) {
-                createdExporter = true;
-                usdzExporter = new USDZExporter();
+            if (result) {
+                quicklookHandler = result.handler;
+                createdExporter = result.created;
             }
-            // if we have created a USDZExporter
-            if (createdExporter)
-                usdzExporter.objectToExport = Context.Current.scene;
 
-            if (usdzExporter) {
+            // if we have created a handler
+            if (createdExporter && quicklookHandler)
+                quicklookHandler.objectToExport = Context.Current.scene;
+
+            if (quicklookHandler) {
                 button.classList.add("this-mode-is-requested");
-                usdzExporter.exportAndOpen().then(() => {
+                quicklookHandler.exportAndOpen().then(() => {
                     button.classList.remove("this-mode-is-requested");
                 }).catch(err => {
                     button.classList.remove("this-mode-is-requested");

package/src/engine/webcomponents/buttons.ts

@@ -3,7 +3,7 @@ import { IContext } from "../engine_types.js";
 import { generateQRCode } from "../engine_utils_qrcode.js";
 import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { getIconElement } from "./icons.js";
-import { NeedleMenu } from "./needle menu/needle-menu.js";
+import { setElementPriority } from "./needle menu/menu-priority.js";
 
 /** 
  * Use the ButtonsFactory to create buttons with icons and functionality   
@@ -67,7 +67,7 @@ export class ButtonsFactory {
         this._fullscreenButton = button;
         button.classList.add("fullscreen-button");
         button.title = "Click to enter fullscreen mode";
-        NeedleMenu.setElementPriority(button, 3);
+        setElementPriority(button, 3);
         const enterFullscreenIcon = getIconElement("fullscreen");
         const exitFullscreenIcon = getIconElement("fullscreen_exit");
         button.appendChild(enterFullscreenIcon);
@@ -119,7 +119,7 @@ export class ButtonsFactory {
         const muteIcon = getIconElement("volume_off");
         const unmuteIcon = getIconElement("volume_up");
 
-        NeedleMenu.setElementPriority(button, 1);
+        setElementPriority(button, 1);
 
         // save state in session storage (this needs consent)
         // if (sessionStorage.getItem("muted") === "true") {
@@ -191,7 +191,7 @@ export class ButtonsFactory {
         qrCodeButton.prepend(getIconElement("qr_code"));
         qrCodeButton.title = "Scan this QR code with your phone to open this page";
         this.hideElementDuringXRSession(qrCodeButton);
-        NeedleMenu.setElementPriority(this._qrButton, 20);
+        setElementPriority(this._qrButton, 20);
 
         const qrCodeContainer = document.createElement("div");
         qrCodeContainer.style.cssText = `

package/src/engine/webcomponents/font-urls.js

@@ -0,0 +1,9 @@
+// Font URLs used by Needle Engine UI.
+// Shared between the runtime (fonts.ts) and the build plugin (plugins/vite/asap.js)
+// to keep preload links and runtime loads in sync.
+
+export const robotoFlexFontUrl = "https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wght@8..144,100..1000&display=swap";
+
+// Using a static (non-variable) font because the variable font is quite large
+// eslint-disable-next-line no-secrets/no-secrets
+export const materialSymbolsFontUrl = "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&display=block";

package/src/engine/webcomponents/fonts.ts

@@ -1,3 +1,4 @@
+import { materialSymbolsFontUrl,robotoFlexFontUrl } from "./font-urls.js";
 
 declare type LoadFontOptions = {
     element?: HTMLElement | DocumentFragment,
@@ -10,11 +11,18 @@ export function loadFont(url: string, opts?: LoadFontOptions) {
     // Add font import to document header.
     // Note that this is slower than it could be, ideally the font would be prefetched,
     // but for that it needs to be in the actual document and not added by JS.
-    const elements = Array.from(element.querySelectorAll(`link[rel=stylesheet][href*='${url}']`));
+    const elements = Array.from(element.querySelectorAll(`link[href*='${url}']`));
     if (elements.length <= 0) {
         const fontLink = document.createElement("link");
         fontLink.href = url;
-        fontLink.rel = "stylesheet";
+        // Load fonts without blocking render: use rel="preload" with onload swap
+        // to stylesheet. This avoids the ~200ms render-blocking delay per font.
+        fontLink.rel = "preload";
+        fontLink.as = "style";
+        // crossorigin must match the HTML <link> attribute (set by asap.js) so the browser
+        // can reuse the cached CORS response instead of making a separate non-CORS request
+        fontLink.crossOrigin = "";
+        fontLink.onload = () => { fontLink.rel = "stylesheet"; };
         element.appendChild(fontLink);
         elements.push(fontLink);
     }
@@ -32,11 +40,8 @@ export function loadFont(url: string, opts?: LoadFontOptions) {
 
 /** Ensure the fonts that needle engine uses are loaded */
 export function ensureFonts() {
-    loadFont("https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wght@8..144,100..1000&display=swap");
+    loadFont(robotoFlexFontUrl);
 }
 
-// add to document head AND shadow dom to work
-// using a static font because the variable font is quite large
-// eslint-disable-next-line no-secrets/no-secrets
-export const iconFontUrl = "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&display=block";
+export { materialSymbolsFontUrl as iconFontUrl };
 // const fontUrl = "./include/fonts/MaterialSymbolsOutlined.css"; // for offline support

package/src/engine/webcomponents/init.ts

@@ -0,0 +1,23 @@
+import { NeedleLogoElement } from "./logo-element.js";
+import { NeedleMenuElement } from "./needle menu/needle-menu.js";
+import { NeedleButtonElement } from "./needle-button.js";
+import { NeedleEngineWebComponent } from "./needle-engine.js";
+
+/** Register all built-in web components. Called from {@link initEngine} as a
+ *  safeguard against aggressive tree-shaking that may drop the top-level
+ *  `customElements.define` calls in the individual component files. */
+export function initWebComponents() {
+    if (typeof window === "undefined") return;
+
+    if (!window.customElements.get("needle-engine"))
+        window.customElements.define("needle-engine", NeedleEngineWebComponent);
+
+    if (!window.customElements.get("needle-button"))
+        window.customElements.define("needle-button", NeedleButtonElement);
+
+    if (!window.customElements.get("needle-logo-element"))
+        window.customElements.define("needle-logo-element", NeedleLogoElement);
+
+    if (!window.customElements.get("needle-menu"))
+        window.customElements.define("needle-menu", NeedleMenuElement);
+}

package/src/engine/webcomponents/logo-element.ts

@@ -17,6 +17,8 @@ export class NeedleLogoElement extends HTMLElement {
     static get elementName() { return elementName; }
 
     static create(): NeedleLogoElement {
+        if (!customElements.get(elementName))
+            customElements.define(elementName, NeedleLogoElement);
         return document.createElement(elementName) as NeedleLogoElement;
     }
 
@@ -131,5 +133,3 @@ export class NeedleLogoElement extends HTMLElement {
     }
 
 }
-if (!customElements.get(elementName))
-    customElements.define(elementName, NeedleLogoElement);

package/src/engine/webcomponents/needle menu/menu-priority.ts

@@ -0,0 +1,20 @@
+/**
+ * Sets the priority attribute on a menu element, determining its position in the menu.
+ * Lower priority elements appear on the left, higher priority on the right.
+ */
+export function setElementPriority(button: HTMLElement, priority: number) {
+    button.setAttribute("priority", String(priority));
+}
+
+/**
+ * Gets the priority attribute from a menu element.
+ * @returns The priority value, or undefined if not set or not a valid number.
+ */
+export function getElementPriority(button: HTMLElement): number | undefined {
+    const priority = button.getAttribute("priority");
+    if (priority) {
+        const val = Number.parseFloat(priority);
+        if (!Number.isNaN(val)) return val;
+    }
+    return undefined;
+}