@needle-tools/engine 4.11.3-next.2d2dff8 → 4.11.3-next.35d1b4d

package/lib/engine/engine_utils_attributes.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @internal
+ */
+export declare namespace InternalAttributeUtils {
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    function isFalsey(value: string | null): boolean;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    function getAttributeValueIfNotFalsey(element: Element, attributeName: string, opts?: {
+        onAttribute: (value: string) => void;
+    }): string | null;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     *
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     *
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    function getAttributeAndCheckFalsey(element: Element, attributeName: string, opts?: {
+        onAttribute: (value: string, falsey: boolean) => void;
+    }): false | string | null;
+}

package/lib/engine/engine_utils_attributes.js

@@ -0,0 +1,70 @@
+/**
+ * @internal
+ */
+export var InternalAttributeUtils;
+(function (InternalAttributeUtils) {
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    function isFalsey(value) {
+        return value === "0" || value?.toLowerCase() === "false";
+    }
+    InternalAttributeUtils.isFalsey = isFalsey;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    function getAttributeValueIfNotFalsey(element, attributeName, opts) {
+        const attrValue = element.getAttribute(attributeName);
+        if (isFalsey(attrValue)) {
+            return null;
+        }
+        opts?.onAttribute?.call(null, attrValue);
+        return attrValue;
+    }
+    InternalAttributeUtils.getAttributeValueIfNotFalsey = getAttributeValueIfNotFalsey;
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     *
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     *
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    function getAttributeAndCheckFalsey(element, attributeName, opts) {
+        const attrValue = element.getAttribute(attributeName);
+        // If the attribute is not set at all we just return
+        if (attrValue === null) {
+            return null;
+        }
+        if (isFalsey(attrValue)) {
+            opts?.onAttribute?.call(null, attrValue, true);
+            return false;
+        }
+        opts?.onAttribute?.call(null, attrValue, false);
+        return attrValue;
+    }
+    InternalAttributeUtils.getAttributeAndCheckFalsey = getAttributeAndCheckFalsey;
+})(InternalAttributeUtils || (InternalAttributeUtils = {}));
+//# sourceMappingURL=engine_utils_attributes.js.map

package/lib/engine/engine_utils_attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine_utils_attributes.js","sourceRoot":"","sources":["../../src/engine/engine_utils_attributes.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,KAAW,sBAAsB,CAiEtC;AAjED,WAAiB,sBAAsB;IAEnC;;;;;;OAMG;IACH,SAAgB,QAAQ,CAAC,KAAoB;QACzC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;IAC7D,CAAC;IAFe,+BAAQ,WAEvB,CAAA;IAED;;;;OAIG;IACH,SAAgB,4BAA4B,CAAC,OAAgB,EAAE,aAAqB,EAAE,IAA+C;QACjI,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;QACtD,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE;YACrB,OAAO,IAAI,CAAC;SACf;QACD,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,SAAU,CAAC,CAAC;QAC1C,OAAO,SAAS,CAAC;IACrB,CAAC;IAPe,mDAA4B,+BAO3C,CAAA;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAgB,0BAA0B,CAAC,OAAgB,EAAE,aAAqB,EAAE,IAA+D;QAC/I,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;QACtD,oDAAoD;QACpD,IAAG,SAAS,KAAK,IAAI,EAAE;YACnB,OAAO,IAAI,CAAC;SACf;QACD,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE;YACrB,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,SAAU,EAAE,IAAI,CAAC,CAAC;YAChD,OAAO,KAAK,CAAC;SAChB;QACD,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,SAAU,EAAE,KAAK,CAAC,CAAC;QACjD,OAAO,SAAS,CAAC;IACrB,CAAC;IAZe,iDAA0B,6BAYzC,CAAA;AAEL,CAAC,EAjEgB,sBAAsB,KAAtB,sBAAsB,QAiEtC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.11.3-next.2d2dff8",
+  "version": "4.11.3-next.35d1b4d",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {

package/src/engine/engine_utils.ts

@@ -4,9 +4,11 @@ import { Quaternion, Vector2, Vector3, Vector4 } from "three";
 declare type Vector = Vector2 | Vector3 | Vector4 | Quaternion;
 
 import { needleLogoOnlySVG } from "./assets/index.js";
+import { isDevEnvironment } from "./debug/debug.js";
 import type { Context } from "./engine_context.js";
 import { ContextRegistry } from "./engine_context_registry.js";
 import { type SourceIdentifier } from "./engine_types.js";
+import { InternalAttributeUtils } from "./engine_utils_attributes.js";
 import type { NeedleEngineWebComponent } from "./webcomponents/needle-engine.js";
 
 // https://schneidenbach.gitbooks.io/typescript-cookbook/content/nameof-operator.html
@@ -908,7 +910,7 @@ export async function PromiseAllWithErrors<T>(promise: Promise<T>[]): Promise<{
  * @param args.colorDark The color of the dark squares
  * @param args.colorLight The color of the light squares
  * @param args.correctLevel The error correction level to use
- * @param args.showLogo If true, the same logo as for the Needle loading screen will be drawn in the center of the QR code
+ * @param args.showLogo If true, the logo will be shown in the center of the QR code. By default the Needle Logo will be used. You can override which logo is being used by setting the `needle-engine` web component's `qr-logo-src` attribute. The logo can also be disabled by setting that attribute to a falsey value (e.g. "0" or "false")
  * @param args.showUrl If true, the URL will be shown below the QR code
  * @param args.domElement The dom element to append the QR code to. If not provided a new div will be created and returned
  * @returns The dom element containing the QR code
@@ -946,16 +948,16 @@ export async function generateQRCode(args: { domElement?: HTMLElement, text: str
     // Number of rows/columns of the generated QR code
     const moduleCount = qrCode?._oQRCode.moduleCount || 0;
     const canvas = qrCode?._oDrawing?._elCanvas as HTMLCanvasElement;
-    
+
     let sizePercentage = 0.25;
     if (moduleCount < 40)
         sizePercentage = Math.floor(moduleCount / 4) / moduleCount;
     else
         sizePercentage = Math.floor(moduleCount / 6) / moduleCount;
-    
+
     const paddingPercentage = Math.floor(moduleCount / 20) / moduleCount;
     try {
-        const img = await addOverlays(canvas, { showLogo: args.showLogo, logoSize: sizePercentage, logoPadding: paddingPercentage }).catch(_e => { /** ignore */ });
+        const img = await internalRenderQRCodeOverlays(canvas, { showLogo: args.showLogo, logoSize: sizePercentage, logoPadding: paddingPercentage }).catch(_e => { /** ignore */ });
         if (img) {
             target.innerHTML = "";
             target.append(img);
@@ -1002,7 +1004,8 @@ export async function generateQRCode(args: { domElement?: HTMLElement, text: str
     return target;
 }
 
-async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean, logoSize?: number, logoPadding?: number }): Promise<HTMLImageElement | void> {
+
+async function internalRenderQRCodeOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean, logoSize?: number, logoPadding?: number }): Promise<HTMLImageElement | void> {
     if (!canvas) return;
 
     // Internal settings
@@ -1019,18 +1022,38 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
     const rectangleRadius = 0;
 
     // Draw the website's icon in the center of the QR code
-    const faviconImage = new Image();
+    const image = new Image();
     const element = document.querySelector("needle-engine") as NeedleEngineWebComponent;
-    const logoSrc = element?.getAttribute("loading-logo-src") || needleLogoOnlySVG;
+    if (!element) {
+        console.debug("[QR Code] No web component found")
+    }
+
+    // Query logo src from needle-engine attribute.
+    // For any supported attribute it's possible to use "falsey" values (e.g. "0" or "false" to disable the logo in the QR code)
+    let logoSrc: false | string | null = null;
+    logoSrc = InternalAttributeUtils.getAttributeAndCheckFalsey(element, "qrcode-logo-src");
+    if (args.showLogo !== true && logoSrc === false) return; // Explictly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "logo-src");
+    if (args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+    logoSrc ||= InternalAttributeUtils.getAttributeAndCheckFalsey(element, "loading-logo-src", {
+        onAttribute: () => {
+            if (isDevEnvironment()) console.warn("[QR Code] 'loading-logo-src' is deprecated, please use 'logo-src' or 'qrcode-logo-src' instead.");
+            else console.debug("[QR Code] 'loading-logo-src' is deprecated.");
+        }
+    });
+    if (args.showLogo !== true && logoSrc === false) return; // Explicitly disabled
+
+    logoSrc ||= needleLogoOnlySVG;
     if (!logoSrc) return;
 
     let haveLogo = false;
     if (args.showLogo !== false) {
-        faviconImage.src = logoSrc;
+        image.src = logoSrc;
         haveLogo = await new Promise((resolve, _reject) => {
-            faviconImage.onload = () => resolve(true);
-            faviconImage.onerror = (err) => {
-                console.error("Error loading favicon image for QR code", err);
+            image.onload = () => resolve(true);
+            image.onerror = (err) => {
+                let errorUrl = logoSrc !== needleLogoOnlySVG ? "'" + logoSrc + "'" : null;
+                console.error("[QR Code] Error loading logo image for QR code", errorUrl, isDevEnvironment() ? err : "");
                 resolve(false);
             };
         });
@@ -1073,7 +1096,7 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
 
     if (haveLogo) {
         // Get aspect of image
-        const aspect = faviconImage.width / faviconImage.height;
+        const aspect = image.width / image.height;
         if (aspect > 1) sizeY = sizeX / aspect;
         else sizeX = sizeY * aspect;
 
@@ -1114,7 +1137,7 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
         paddedContext.shadowColor = "transparent";
         const logoX = (paddedCanvas.width - sizeX) / 2;
         const logoY = (paddedCanvas.height - sizeY) / 2;
-        paddedContext.drawImage(faviconImage, logoX, logoY, sizeX, sizeY);
+        paddedContext.drawImage(image, logoX, logoY, sizeX, sizeY);
     }
 
     // Replace the canvas with the padded one
@@ -1125,4 +1148,5 @@ async function addOverlays(canvas: HTMLCanvasElement, args: { showLogo?: boolean
     img.style.height = "auto";
 
     return img;
-}
+}
+

package/src/engine/engine_utils_attributes.ts

@@ -0,0 +1,72 @@
+
+
+/**
+ * @internal
+ */
+export namespace InternalAttributeUtils {
+
+    /**
+     * Checks if the given value is considered "falsey" in the context of HTML attributes.
+     * A value is considered falsey if it is "0" or "false" (case-insensitive).
+     *
+     * @param value - The attribute value to check.
+     * @returns True if the value is falsey, otherwise false.
+     */
+    export function isFalsey(value: string | null): boolean {
+        return value === "0" || value?.toLowerCase() === "false";
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns null.
+     * @returns The attribute value or null if falsey.
+     */
+    export function getAttributeValueIfNotFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string) => void }): string | null {
+        const attrValue = element.getAttribute(attributeName);
+        if (isFalsey(attrValue)) {
+            return null;
+        }
+        opts?.onAttribute?.call(null, attrValue!);
+        return attrValue;
+    }
+
+    /**
+     * Retrieves the value of the specified attribute from the given element.
+     * If the attribute value is considered falsey, it returns false.
+     * If the attribute is not set at all, it returns null.
+     * @returns The attribute value, false if falsey, or null if not set.
+     * 
+     * @example
+     * ```typescript
+     * const result = HTMLAttributeUtils.getAttributeAndCheckFalsey(element, 'data-example', {
+     *     onAttribute: (value, falsey) => {
+     *         console.log(`Attribute value: ${value}
+     * , Is falsey: ${falsey}`);
+     *     }
+     * });
+     * 
+     * if (result === false) {
+     *     console.log('The attribute is set to a falsey value.');
+     * } else if (result === null) {
+     *     console.log('The attribute is not set.');
+     * } else {
+     *     console.log(`The attribute value is: ${result}`);
+     * }
+     * ```
+     */
+    export function getAttributeAndCheckFalsey(element: Element, attributeName: string, opts?: { onAttribute: (value: string, falsey:boolean) => void }): false | string | null {
+        const attrValue = element.getAttribute(attributeName);
+        // If the attribute is not set at all we just return
+        if(attrValue === null) {
+            return null;
+        }
+        if (isFalsey(attrValue)) {
+            opts?.onAttribute?.call(null, attrValue!, true);
+            return false;
+        }
+        opts?.onAttribute?.call(null, attrValue!, false);
+        return attrValue;
+    }
+
+}
+