@needle-tools/engine 5.0.0 → 5.1.0-experimental.1

package/src/engine-components/ui/Text.ts

@@ -27,7 +27,7 @@ export enum VerticalWrapMode {
     Truncate = 0,
     Overflow = 1,
 }
-enum HorizontalWrapMode {
+export enum HorizontalWrapMode {
     Wrap = 0,
     Overflow = 1,
 }
@@ -70,33 +70,149 @@ export enum FontStyle {
  */
 export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiver {
 
+    /**
+     * The alignment of the text within its container. This determines how the text is anchored and positioned relative to its RectTransform. For example, `UpperLeft` will anchor the text to the upper left corner of the container, while `MiddleCenter` will center the text both horizontally and vertically. Changing this property will update the underlying three-mesh-ui options and mark the UI as dirty to trigger a re-render.
+     */
     @serializable()
-    alignment: TextAnchor = TextAnchor.UpperLeft;
+    set alignment(val: TextAnchor) {
+        if (val !== this._alignment) {
+            this._alignment = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get alignment(): TextAnchor {
+        return this._alignment;
+    }
+    private _alignment: TextAnchor = TextAnchor.UpperLeft;
+
+    /**
+     * Determines how text that exceeds the vertical bounds of the container is handled. If set to `Truncate`, any text that goes beyond the vertical limits of the container will be cut off and not visible. If set to `Overflow`, the text will continue to render outside the container bounds, which may result in it being partially or fully visible depending on the layout and parent containers.
+     * @default VerticalWrapMode.Truncate
+     */
     @serializable()
-    verticalOverflow: VerticalWrapMode = VerticalWrapMode.Truncate;
+    set verticalOverflow(val: VerticalWrapMode) {
+        if (val !== this._verticalOverflow) {
+            this._verticalOverflow = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get verticalOverflow(): VerticalWrapMode {
+        return this._verticalOverflow;
+    }
+    private _verticalOverflow: VerticalWrapMode = VerticalWrapMode.Truncate;
+
+    /**
+     * Determines how text that exceeds the horizontal bounds of the container is handled. If set to `Wrap`, the text will automatically wrap to the next line when it reaches the edge of the container. If set to `Overflow`, the text will continue on a single line and may overflow outside the container bounds.
+     * @default HorizontalWrapMode.Wrap
+     */
     @serializable()
-    horizontalOverflow: HorizontalWrapMode = HorizontalWrapMode.Wrap;
+    set horizontalOverflow(val: HorizontalWrapMode) {
+        if (val !== this._horizontalOverflow) {
+            this._horizontalOverflow = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get horizontalOverflow(): HorizontalWrapMode {
+        return this._horizontalOverflow;
+    }
+    private _horizontalOverflow: HorizontalWrapMode = HorizontalWrapMode.Wrap;
+
+    /**
+     * The line spacing multiplier for the text. A value of 1 means normal spacing, 1.5 means 50% more spacing, and 0.5 means 50% less spacing.
+     * @default 1
+     */
     @serializable()
-    lineSpacing: number = 1;
+    set lineSpacing(val: number) {
+        if (val !== this._lineSpacing) {
+            this._lineSpacing = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get lineSpacing(): number {
+        return this._lineSpacing;
+    }
+    private _lineSpacing: number = 1;
+
+    /**
+     * The style of the font, which can be normal, bold, italic, or bold and italic.   
+     * 
+     * This is used to determine the correct font variant to use based on the provided `font` property. For example, if you set `font` to "Arial" and `fontStyle` to `FontStyle.Bold`, it will look for a font variant named "Arial-Bold" (or "arial-bold") in the font library. If such a variant exists, it will be used to render the text with the specified style.
+     * 
+     * @default FontStyle.Normal
+     */
     @serializable()
-    supportRichText: boolean = false;
+    set fontStyle(val: FontStyle) {
+        if (val !== this._fontStyle) {
+            this._fontStyle = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get fontStyle(): FontStyle {
+        return this._fontStyle;
+    }
+    private _fontStyle: FontStyle = FontStyle.Normal;
+
+    /**
+     * The font to use for the text, specified as a URL to a font file.   
+     * 
+     * The font file must be in MSDF format. You can generate MSDF fonts using tools like [msdf-bmfont-xml](https://github.com/Chlumsky/msdf-bmfont-xml) or by using Needle Engine for Unity where the Needle Engine integration automatically generates MSDF fonts for used font assets.
+     * 
+     * @default "https://cdn.needle.tools/static/fonts/msdf/arial/arial"
+     */
     @serializable(URL)
-    font?: string;
+    set font(val: string | null) {
+        if (val !== this._font) {
+            this._font = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get font(): string | null {
+        return this._font;
+    }
+    private _font: string | null = "https://cdn.needle.tools/static/fonts/msdf/arial/arial";
+
+
+    /**
+     * Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
+     * @default false
+     */
     @serializable()
-    fontStyle: FontStyle = FontStyle.Normal;
+    set supportRichText(val: boolean) {
+        if (val !== this._supportRichText) {
+            this._supportRichText = val;
+            this.uiObject?.set(this.getTextOpts());
+            this.markDirty();
+        }
+    }
+    get supportRichText(): boolean {
+        return this._supportRichText;
+    }
+    private _supportRichText: boolean = false;
+
 
-    // private _alphaFactor : number = 1;
+    /**
+     * Set the alpha factor for the text, which multiplies with the color's alpha to determine overall transparency.
+     */
     setAlphaFactor(factor: number): void {
         super.setAlphaFactor(factor);
         this.uiObject?.set({ fontOpacity: this.color.alpha * this.alphaFactor });
         this.markDirty();
     }
 
+    /**
+     * The text content to display. Supports basic rich text tags like `<b>`, `<i>`, and `<color=hex>` if `supportRichText` is enabled.
+     * @default ""
+     */
     @serializable()
     get text(): string {
         return this._text;
     }
-
     set text(val: string) {
         if (val !== this._text) {
             this._text = val;
@@ -105,6 +221,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
             this.context.accessibility.updateElement(this, { label: this.text });
         }
     }
+    private _text: string = "";
 
     private set_text(val: string) {
         this.text = val;
@@ -120,6 +237,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         this._fontSize = val;
         this.uiObject?.set({ fontSize: val });
     }
+    private _fontSize: number = 12;
 
     private sRGBTextColor: Color = new Color(1, 0, 1);
     protected onColorChanged(): void {
@@ -158,26 +276,6 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
     protected onCreate(_opts: any): void {
         if (debug) console.log(this);
 
-        if (this.horizontalOverflow == HorizontalWrapMode.Overflow) {
-            // Only line characters in the textContent (\n,\r\t) would be able to multiline the text
-            _opts.whiteSpace = 'pre';
-        }
-
-        if (this.verticalOverflow == VerticalWrapMode.Truncate) {
-            this.context.renderer.localClippingEnabled = true;
-            _opts.overflow = 'hidden';
-        }
-
-
-        // @marwie : this combination is currently KO. See sample "Overflow Overview"
-        if (this.horizontalOverflow == HorizontalWrapMode.Overflow && this.verticalOverflow == VerticalWrapMode.Truncate) {
-            // This could fix this combination, but would require anchors updates to replace element
-            // _opts.width = 'auto';
-        }
-
-
-        _opts.lineHeight = this.lineSpacing;
-
         // @marwie : Should be fixed. Currently _opts are always fed with :
         //          backgroundOpacity : color.opacity
         //          backgroundColor : color
@@ -190,8 +288,6 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
             _opts.backgroundOpacity = 0.5;
         }
 
-        const rt = this.rectTransform;
-
         // Texts now support both options, block and inline, and inline has all default to inherit
         _opts = { ..._opts, ...this.getTextOpts() };
 
@@ -202,6 +298,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
             _opts.backgroundOpacity = 0.1;
         }
 
+        const rt = this.rectTransform;
         this.uiObject = rt.createNewText(_opts);
         this.feedText(this.text, this.supportRichText);
 
@@ -212,8 +309,6 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         this.handleTextRenderOnTop();
     }
 
-    private _text: string = "";
-    private _fontSize: number = 12;
 
     private _textMeshUi: Array<ThreeMeshUI.Inline> | null = null;
 
@@ -224,14 +319,36 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         //     fontSize /= this.canvas?.scaleFactor;
         // }
 
-
-        const textOpts = {
+        const textOpts: {
+            color: Color,
+            fontOpacity: number,
+            fontSize: number,
+            fontKerning: string,
+            whiteSpace?: string,
+            overflow?: string,
+            lineHeight?: number
+        } = {
             color: this.color,
             fontOpacity: this.color.alpha,
             fontSize: fontSize,
             fontKerning: "normal",
-
         };
+
+        if (this.horizontalOverflow == HorizontalWrapMode.Overflow) {
+            // Only line characters in the textContent (\n,\r\t) would be able to multiline the text
+            textOpts.whiteSpace = 'pre';
+        }
+        if (this.verticalOverflow == VerticalWrapMode.Truncate) {
+            this.context.renderer.localClippingEnabled = true;
+            textOpts.overflow = 'hidden';
+        }
+        // @marwie : this combination is currently KO. See sample "Overflow Overview"
+        if (this.horizontalOverflow == HorizontalWrapMode.Overflow && this.verticalOverflow == VerticalWrapMode.Truncate) {
+            // This could fix this combination, but would require anchors updates to replace element
+            // textOpts.width = 'auto';
+        }
+        textOpts.lineHeight = this.lineSpacing;
+
         this.setFont(textOpts as ThreeMeshUIEveryOptions, this.fontStyle);
         return textOpts;
     }
@@ -486,15 +603,16 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
      * @private
      */
     private setFont(opts: ThreeMeshUIEveryOptions, fontStyle: FontStyle) {
+        
+        if (!this.font) {
+            if(debug) console.warn("No font set for Text component, skipping font setup");
+            return;
+        }
 
-        // @TODO : THH could be useful to uniformize font family name :
-        //         This would ease possible html/vr matching
-        //              -   Arial instead of assets/arial
-        //              -   Arial should stay Arial instead of arial
-        if (!this.font) return;
         const fontName = this.font;
         const familyName = this.getFamilyNameWithCorrectSuffix(fontName, fontStyle);
-        if (debug) console.log("Selected font family:" + familyName);
+
+        if (debug) console.log("Selected font family:" + familyName, this.font);
 
         // ensure a font family is register under this name
         let fontFamily = ThreeMeshUI.FontLibrary.getFontFamily(familyName as string);
@@ -527,9 +645,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
                 opts.fontWeight = 400;
         }
 
-
         // Ensure a fontVariant is registered
-        //@TODO: @swingingtom add type for fontWeight
         let fontVariant = fontFamily.getVariant(opts.fontWeight as any as string, opts.fontStyle);
         if (!fontVariant) {
             let jsonPath = familyName;
@@ -550,13 +666,7 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
 
     private getFamilyNameWithCorrectSuffix(familyName: string, style: FontStyle): string {
 
-
-        // the URL decorator resolves the URL to absolute URLs - we need to remove the domain part since we're only interested in the path
-        if (familyName.startsWith("https:") || familyName.startsWith("http:")) {
-            const url = new URL(familyName);
-            familyName = url.pathname;
-        }
-
+        const isAbsolute = familyName.startsWith("https:") || familyName.startsWith("http:");
 
         // we can only change the style for the family if the name has a suffix (e.g. Arial-Bold)
         const styleSeparator = familyName.lastIndexOf('-');
@@ -580,8 +690,16 @@ export class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiv
         }
         const isUpperCase = fontBaseName[0] === fontBaseName[0].toUpperCase();
         const fontNameWithoutSuffix = familyName.substring(0, styleSeparator > pathSeparatorIndex ? styleSeparator : familyName.length);
+
         if (debug) console.log("Select font: ", familyName, FontStyle[style], fontBaseName, isUpperCase, fontNameWithoutSuffix);
 
+        /**
+         * If a user provides a font with an absolute URL AND the font name does not end with "-msdf.json" or ".png" (e.g. "https://example.com/fonts/Arial-Bold"), we will assume that the user is providing the full path to the font files and we will not try to modify the font name based on the style. This allows users to have more control over the font files they are using, especially if they are hosting their own fonts or using a custom font provider that does not follow the same naming conventions as our default fonts.
+         */
+        if (isAbsolute && (!familyName.endsWith("-msdf.json") || !familyName.endsWith(".png"))) {
+            return fontNameWithoutSuffix;
+        }
+
         switch (style) {
             case FontStyle.Normal:
                 if (isUpperCase) return fontNameWithoutSuffix + "-Regular";

package/src/engine-components/ui/index.ts

@@ -1 +1,2 @@
-export * from "./PointerEvents.js"
+export * from "./PointerEvents.js";
+export * from "./Text.js";