@lightningjs/renderer 3.0.0-beta14 → 3.0.0-beta15

package/src/core/text-rendering/{sdf/Utils.ts → TextLayoutEngine.ts}

@@ -1,37 +1,142 @@
-/*
- * If not stated otherwise in this file or this component's LICENSE file the
- * following copyright and licenses apply:
- *
- * Copyright 2025 Comcast Cable Communications Management, LLC.
- *
- * Licensed under the Apache License, Version 2.0 (the License);
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
+import type {
+  FontMetrics,
+  MeasureTextFn,
+  NormalizedFontMetrics,
+  TextLayoutStruct,
+  TextLineStruct,
+  WrappedLinesStruct,
+} from './TextRenderer.js';
+
+export const defaultFontMetrics: FontMetrics = {
+  ascender: 800,
+  descender: -200,
+  lineGap: 200,
+  unitsPerEm: 1000,
+};
+
+export const normalizeFontMetrics = (
+  metrics: FontMetrics,
+  fontSize: number,
+): NormalizedFontMetrics => {
+  const scale = fontSize / metrics.unitsPerEm;
+  return {
+    ascender: metrics.ascender * scale,
+    descender: metrics.descender * scale,
+    lineGap: metrics.lineGap * scale,
+  };
+};
+
+export const mapTextLayout = (
+  measureText: MeasureTextFn,
+  metrics: NormalizedFontMetrics,
+  text: string,
+  textAlign: string,
+  verticalAlign: string,
+  fontFamily: string,
+  lineHeight: number,
+  overflowSuffix: string,
+  wordBreak: string,
+  letterSpacing: number,
+  maxLines: number,
+  maxWidth: number,
+  maxHeight: number,
+): TextLayoutStruct => {
+  const ascPx = metrics.ascender;
+  const descPx = metrics.descender;
+
+  const bareLineHeight = ascPx - descPx;
+  const lineHeightPx =
+    lineHeight <= 3 ? lineHeight * bareLineHeight : lineHeight;
+  const lineHeightDelta = lineHeightPx - bareLineHeight;
+  const halfDelta = lineHeightDelta * 0.5;
+
+  let effectiveMaxLines = maxLines;
+  if (maxHeight > 0) {
+    const maxFromHeight = Math.floor(maxHeight / lineHeightPx);
+    if (effectiveMaxLines === 0 || maxFromHeight < effectiveMaxLines) {
+      effectiveMaxLines = maxFromHeight;
+    }
+  }
+
+  const wrappedText = maxWidth > 0;
+  //wrapText or just measureLines based on maxWidth
+  const [lines, remainingLines, remainingText] =
+    wrappedText === true
+      ? wrapText(
+          measureText,
+          text,
+          fontFamily,
+          maxWidth,
+          letterSpacing,
+          overflowSuffix,
+          wordBreak,
+          maxLines,
+        )
+      : measureLines(
+          measureText,
+          text.split('\n'),
+          fontFamily,
+          letterSpacing,
+          maxLines,
+        );
+
+  let effectiveLineAmount = lines.length;
+  let effectiveMaxWidth = lines[0]![1];
+
+  //check for longest line
+  if (effectiveLineAmount > 1) {
+    for (let i = 1; i < effectiveLineAmount; i++) {
+      effectiveMaxWidth = Math.max(effectiveMaxWidth, lines[i]![1]);
+    }
+  }
+
+  //update line x offsets
+  if (textAlign !== 'left') {
+    const maxW = wrappedText === true ? maxWidth : effectiveMaxWidth;
+    for (let i = 0; i < effectiveLineAmount; i++) {
+      const line = lines[i]!;
+      const w = line[1];
+      line[2] = textAlign === 'right' ? maxW - w : (maxW - w) / 2;
+    }
+  }
+
+  const effectiveMaxHeight = effectiveLineAmount * lineHeightPx;
+
+  let firstBaseLine = halfDelta;
+  if (maxHeight > 0 && verticalAlign !== 'top') {
+    if (verticalAlign === 'middle') {
+      firstBaseLine += (maxHeight - effectiveMaxHeight) / 2;
+    } else {
+      firstBaseLine += maxHeight - effectiveMaxHeight;
+    }
+  }
+
+  const startY = firstBaseLine;
+  for (let i = 0; i < effectiveLineAmount; i++) {
+    const line = lines[i] as TextLineStruct;
+    line[3] = startY + lineHeightPx * i;
+  }
 
-import { isZeroWidthSpace } from '../Utils.js';
-import * as SdfFontHandler from '../SdfFontHandler.js';
-import type { TextLineStruct, WrappedLinesStruct } from '../TextRenderer.js';
+  return [
+    lines,
+    remainingLines,
+    remainingText,
+    bareLineHeight,
+    lineHeightPx,
+    effectiveMaxWidth,
+    effectiveMaxHeight,
+  ];
+};
 
 export const measureLines = (
+  measureText: MeasureTextFn,
   lines: string[],
   fontFamily: string,
   letterSpacing: number,
-  fontScale: number,
   maxLines: number,
-  hasMaxLines: boolean,
 ): WrappedLinesStruct => {
   const measuredLines: TextLineStruct[] = [];
-  const designLetterSpacing = letterSpacing * fontScale;
-  let remainingLines = hasMaxLines === true ? maxLines : lines.length;
+  let remainingLines = maxLines > 0 ? maxLines : lines.length;
   let i = 0;
 
   while (remainingLines > 0) {
@@ -41,71 +146,90 @@ export const measureLines = (
     if (line === undefined) {
       continue;
     }
-    const width = measureText(line, fontFamily, designLetterSpacing);
-    measuredLines.push([line, width]);
+    const width = measureText(line, fontFamily, letterSpacing);
+    measuredLines.push([line, width, 0, 0]);
   }
 
   return [
     measuredLines,
     remainingLines,
-    hasMaxLines === true ? lines.length - measuredLines.length > 0 : false,
+    maxLines > 0 ? lines.length - measuredLines.length > 0 : false,
   ];
 };
-/**
- * Wrap text for SDF rendering with proper width constraints
- */
+
 export const wrapText = (
+  measureText: MeasureTextFn,
   text: string,
   fontFamily: string,
-  fontScale: number,
   maxWidth: number,
   letterSpacing: number,
   overflowSuffix: string,
   wordBreak: string,
   maxLines: number,
-  hasMaxLines: boolean,
 ): WrappedLinesStruct => {
   const lines = text.split('\n');
   const wrappedLines: TextLineStruct[] = [];
-  const maxWidthInDesignUnits = maxWidth / fontScale;
-  const designLetterSpacing = letterSpacing * fontScale;
 
   // Calculate space width for line wrapping
-  const spaceWidth = measureText(' ', fontFamily, designLetterSpacing);
+  const spaceWidth = measureText(' ', fontFamily, letterSpacing);
 
   let wrappedLine: TextLineStruct[] = [];
   let remainingLines = maxLines;
   let hasRemainingText = true;
+  let hasMaxLines = maxLines > 0;
 
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!;
+    const line = lines[i];
+    if (line === undefined) {
+      continue;
+    }
 
-    [wrappedLine, remainingLines, hasRemainingText] = wrapLine(
-      line,
-      fontFamily,
-      maxWidthInDesignUnits,
-      designLetterSpacing,
-      spaceWidth,
-      overflowSuffix,
-      wordBreak,
-      remainingLines,
-      hasMaxLines,
-    );
+    [wrappedLine, remainingLines, hasRemainingText] =
+      line.length > 0
+        ? wrapLine(
+            measureText,
+            line,
+            fontFamily,
+            maxWidth,
+            letterSpacing,
+            spaceWidth,
+            overflowSuffix,
+            wordBreak,
+            remainingLines,
+            hasMaxLines,
+          )
+        : [[['', 0, 0, 0]], remainingLines, i < lines.length - 1];
 
+    remainingLines--;
     wrappedLines.push(...wrappedLine);
+
+    if (hasMaxLines === true && remainingLines <= 0) {
+      const lastLine = wrappedLines[wrappedLines.length - 1]!;
+      if (i < lines.length - 1) {
+        if (lastLine[0].endsWith(overflowSuffix) === false) {
+          lastLine[0] = truncateLineWithSuffix(
+            measureText,
+            lastLine[0],
+            fontFamily,
+            maxWidth,
+            letterSpacing,
+            overflowSuffix,
+          );
+        }
+      }
+      break;
+    }
   }
 
   return [wrappedLines, remainingLines, hasRemainingText];
 };
 
-/**
- * Wrap a single line of text for SDF rendering
- */
 export const wrapLine = (
+  measureText: MeasureTextFn,
   line: string,
   fontFamily: string,
   maxWidth: number,
-  designLetterSpacing: number,
+  letterSpacing: number,
   spaceWidth: number,
   overflowSuffix: string,
   wordBreak: string,
@@ -129,7 +253,7 @@ export const wrapLine = (
       continue;
     }
     const space = spaces[i - 1] || '';
-    const wordWidth = measureText(word, fontFamily, designLetterSpacing);
+    const wordWidth = measureText(word, fontFamily, letterSpacing);
     // For width calculation, treat ZWSP as having 0 width but regular space functionality
     const effectiveSpaceWidth = space === '\u200B' ? 0 : spaceWidth;
     const totalWidth = currentLineWidth + effectiveSpaceWidth + wordWidth;
@@ -165,25 +289,23 @@ export const wrapLine = (
       }
 
       if (wordBreak !== 'break-all' && currentLine.length > 0) {
-        wrappedLines.push([currentLine, currentLineWidth]);
-        currentLine = '';
-        currentLineWidth = 0;
-        remainingLines--;
+        wrappedLines.push([currentLine, currentLineWidth, 0, 0]);
       }
 
       if (wordBreak !== 'break-all') {
+        remainingLines--;
         currentLine = word;
         currentLineWidth = wordWidth;
       }
 
       if (wordBreak === 'break-word') {
         const [lines, rl, rt] = breakWord(
+          measureText,
           word,
           fontFamily,
           maxWidth,
-          designLetterSpacing,
+          letterSpacing,
           remainingLines,
-          hasMaxLines,
         );
         remainingLines = rl;
         hasRemainingText = rt;
@@ -198,16 +320,17 @@ export const wrapLine = (
           }
         }
       } else if (wordBreak === 'break-all') {
-        const codepoint = word.codePointAt(0)!;
-        const glyph = SdfFontHandler.getGlyph(fontFamily, codepoint);
-        const firstLetterWidth =
-          glyph !== null ? glyph.xadvance + designLetterSpacing : 0;
+        const firstLetterWidth = measureText(
+          word.charAt(0),
+          fontFamily,
+          letterSpacing,
+        );
         let linebreak = false;
         if (
           currentLineWidth + firstLetterWidth + effectiveSpaceWidth >
           maxWidth
         ) {
-          wrappedLines.push([currentLine, currentLineWidth]);
+          wrappedLines.push([currentLine, currentLineWidth, 0, 0]);
           remainingLines -= 1;
           currentLine = '';
           currentLineWidth = 0;
@@ -215,13 +338,13 @@ export const wrapLine = (
         }
         const initial = maxWidth - currentLineWidth;
         const [lines, rl, rt] = breakAll(
+          measureText,
           word,
           fontFamily,
           initial,
           maxWidth,
-          designLetterSpacing,
+          letterSpacing,
           remainingLines,
-          hasMaxLines,
         );
         remainingLines = rl;
         hasRemainingText = rt;
@@ -229,13 +352,13 @@ export const wrapLine = (
           const [text, width] = lines[0]!;
           currentLine += ' ' + text;
           currentLineWidth = width;
-          wrappedLines.push([currentLine, currentLineWidth]);
+          wrappedLines.push([currentLine, currentLineWidth, 0, 0]);
         }
 
         for (let j = 1; j < lines.length; j++) {
           [currentLine, currentLineWidth] = lines[j]!;
           if (j < lines.length - 1) {
-            wrappedLines.push([currentLine, currentLineWidth]);
+            wrappedLines.push([currentLine, currentLineWidth, 0, 0]);
           }
         }
       }
@@ -243,81 +366,35 @@ export const wrapLine = (
   }
 
   // Add the last line if it has content
-  if (currentLine.length > 0 && remainingLines === 0) {
+  if (currentLine.length > 0 && hasMaxLines === true && remainingLines === 0) {
     currentLine = truncateLineWithSuffix(
+      measureText,
       currentLine,
       fontFamily,
       maxWidth,
-      designLetterSpacing,
+      letterSpacing,
       overflowSuffix,
     );
   }
 
   if (currentLine.length > 0) {
-    wrappedLines.push([currentLine, currentLineWidth]);
-  } else {
-    wrappedLines.push(['', 0]);
+    wrappedLines.push([currentLine, currentLineWidth, 0, 0]);
   }
   return [wrappedLines, remainingLines, hasRemainingText];
 };
 
-/**
- * Measure the width of text in SDF design units
- */
-export const measureText = (
-  text: string,
-  fontFamily: string,
-  designLetterSpacing: number,
-): number => {
-  let width = 0;
-  let prevCodepoint = 0;
-  for (let i = 0; i < text.length; i++) {
-    const char = text.charAt(i);
-    const codepoint = text.codePointAt(i);
-    if (codepoint === undefined) continue;
-
-    // Skip zero-width spaces in width calculations
-    if (isZeroWidthSpace(char)) {
-      continue;
-    }
-
-    const glyph = SdfFontHandler.getGlyph(fontFamily, codepoint);
-    if (glyph === null) continue;
-
-    let advance = glyph.xadvance;
-
-    // Add kerning if there's a previous character
-    if (prevCodepoint !== 0) {
-      const kerning = SdfFontHandler.getKerning(
-        fontFamily,
-        prevCodepoint,
-        codepoint,
-      );
-      advance += kerning;
-    }
-
-    width += advance + designLetterSpacing;
-    prevCodepoint = codepoint;
-  }
-
-  return width;
-};
-
 /**
  * Truncate a line with overflow suffix to fit within width
  */
 export const truncateLineWithSuffix = (
+  measureText: MeasureTextFn,
   line: string,
   fontFamily: string,
   maxWidth: number,
-  designLetterSpacing: number,
+  letterSpacing: number,
   overflowSuffix: string,
 ): string => {
-  const suffixWidth = measureText(
-    overflowSuffix,
-    fontFamily,
-    designLetterSpacing,
-  );
+  const suffixWidth = measureText(overflowSuffix, fontFamily, letterSpacing);
 
   if (suffixWidth >= maxWidth) {
     return overflowSuffix.substring(0, Math.max(1, overflowSuffix.length - 1));
@@ -325,11 +402,7 @@ export const truncateLineWithSuffix = (
 
   let truncatedLine = line;
   while (truncatedLine.length > 0) {
-    const lineWidth = measureText(
-      truncatedLine,
-      fontFamily,
-      designLetterSpacing,
-    );
+    const lineWidth = measureText(truncatedLine, fontFamily, letterSpacing);
     if (lineWidth + suffixWidth <= maxWidth) {
       return truncatedLine + overflowSuffix;
     }
@@ -343,12 +416,12 @@ export const truncateLineWithSuffix = (
  * wordbreak function: https://developer.mozilla.org/en-US/docs/Web/CSS/word-break#break-word
  */
 export const breakWord = (
+  measureText: MeasureTextFn,
   word: string,
   fontFamily: string,
   maxWidth: number,
-  designLetterSpacing: number,
+  letterSpacing: number,
   remainingLines: number,
-  hasMaxLines: boolean,
 ): WrappedLinesStruct => {
   const lines: TextLineStruct[] = [];
   let currentPart = '';
@@ -360,17 +433,14 @@ export const breakWord = (
     const codepoint = char.codePointAt(0);
     if (codepoint === undefined) continue;
 
-    const glyph = SdfFontHandler.getGlyph(fontFamily, codepoint);
-    if (glyph === null) continue;
-
-    const charWidth = glyph.xadvance + designLetterSpacing;
+    const charWidth = measureText(char, fontFamily, letterSpacing);
 
     if (currentWidth + charWidth > maxWidth && currentPart.length > 0) {
       remainingLines--;
       if (remainingLines === 0) {
         break;
       }
-      lines.push([currentPart, currentWidth]);
+      lines.push([currentPart, currentWidth, 0, 0]);
       currentPart = char;
       currentWidth = charWidth;
     } else {
@@ -380,7 +450,7 @@ export const breakWord = (
   }
 
   if (currentPart.length > 0) {
-    lines.push([currentPart, currentWidth]);
+    lines.push([currentPart, currentWidth, 0, 0]);
   }
 
   return [lines, remainingLines, i < word.length - 1];
@@ -390,13 +460,13 @@ export const breakWord = (
  * wordbreak function: https://developer.mozilla.org/en-US/docs/Web/CSS/word-break#break-word
  */
 export const breakAll = (
+  measureText: MeasureTextFn,
   word: string,
   fontFamily: string,
   initial: number,
   maxWidth: number,
-  designLetterSpacing: number,
+  letterSpacing: number,
   remainingLines: number,
-  hasMaxLines: boolean,
 ): WrappedLinesStruct => {
   const lines: TextLineStruct[] = [];
   let currentPart = '';
@@ -411,13 +481,9 @@ export const breakAll = (
       break;
     }
     const char = word.charAt(i);
-    const codepoint = char.codePointAt(0)!;
-    const glyph = SdfFontHandler.getGlyph(fontFamily, codepoint);
-    if (glyph === null) continue;
-
-    const charWidth = glyph.xadvance + designLetterSpacing;
+    const charWidth = measureText(char, fontFamily, letterSpacing);
     if (currentWidth + charWidth > max && currentPart.length > 0) {
-      lines.push([currentPart, currentWidth]);
+      lines.push([currentPart, currentWidth, 0, 0]);
       currentPart = char;
       currentWidth = charWidth;
       max = maxWidth;
@@ -429,7 +495,7 @@ export const breakAll = (
   }
 
   if (currentPart.length > 0) {
-    lines.push([currentPart, currentWidth]);
+    lines.push([currentPart, currentWidth, 0, 0]);
   }
 
   return [lines, remainingLines, hasRemainingText];

package/src/core/text-rendering/TextRenderer.ts

@@ -198,16 +198,6 @@ export interface TrProps extends TrFontProps {
    * @default 0
    */
   maxLines: number;
-  /**
-   * Baseline for text
-   *
-   * @remarks
-   * This property sets the text baseline used when drawing text.
-   * Not yet implemented in the SDF renderer.
-   *
-   * @default alphabetic
-   */
-  textBaseline: TextBaseline;
   /**
    * Vertical Align for text when lineHeight > fontSize
    *
@@ -335,6 +325,15 @@ export interface FontLoadOptions {
   atlasDataUrl?: string;
 }
 
+/**
+ * Measure Width of Text function to be defined in font handlers, used in TextLayoutEngine
+ */
+export type MeasureTextFn = (
+  text: string,
+  fontFamily: string,
+  letterSpacing: number,
+) => number;
+
 export interface FontHandler {
   init: (
     c: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
@@ -350,7 +349,7 @@ export interface FontHandler {
     fontFamily: string,
     fontSize: number,
   ) => NormalizedFontMetrics;
-  setFontMetrics: (fontFamily: string, metrics: NormalizedFontMetrics) => void;
+  measureText: MeasureTextFn;
 }
 
 export interface TextRenderProps {
@@ -371,6 +370,8 @@ export interface TextRenderProps {
 export interface TextRenderInfo {
   width: number;
   height: number;
+  hasRemainingText?: boolean;
+  remainingLines?: number;
   imageData?: ImageData | null; // Image data for Canvas Text Renderer
   layout?: TextLayout; // Layout data for SDF renderer caching
 }
@@ -378,7 +379,7 @@ export interface TextRenderInfo {
 export interface TextRenderer {
   type: 'canvas' | 'sdf';
   font: FontHandler;
-  renderText: (stage: Stage, props: CoreTextNodeProps) => TextRenderInfo;
+  renderText: (props: CoreTextNodeProps) => TextRenderInfo;
   // Updated to accept layout data and return vertex buffer for performance
   addQuads: (layout?: TextLayout) => Float32Array | null;
   renderQuads: (
@@ -394,8 +395,10 @@ export interface TextRenderer {
  * Text line struct for text mapping
  * 0 - text
  * 1 - width
+ * 2 - line offset x
+ * 3 - line offset y
  */
-export type TextLineStruct = [string, number];
+export type TextLineStruct = [string, number, number, number];
 
 /**
  * Wrapped lines struct for text mapping
@@ -404,3 +407,23 @@ export type TextLineStruct = [string, number];
  * 2 - remaining text
  */
 export type WrappedLinesStruct = [TextLineStruct[], number, boolean];
+
+/**
+ * Wrapped lines struct for text mapping
+ * 0 - line structs
+ * 1 - remaining lines
+ * 2 - remaining text
+ * 3 - bare line height
+ * 4 - line height pixels
+ * 5 - effective width
+ * 6 - effective height
+ */
+export type TextLayoutStruct = [
+  TextLineStruct[],
+  number,
+  boolean,
+  number,
+  number,
+  number,
+  number,
+];