@stats-forge/github-stats-forge-core 0.0.1 → 0.1.0

package/src/common/render.ts

@@ -1,21 +1,16 @@
-import { getCardColors, isPrefixedHexColor } from './color.js';
-import { SECONDARY_ERROR_MESSAGES, TRY_AGAIN_LATER } from './error.js';
-import { kFormatter } from './fmt.js';
-import { encodeHTML } from './html.js';
-import { clampValue } from './ops.js';
+import type { Child, Declarations, MarkupElement } from '../markup/index.ts';
+import { el, renderMarkup, rule, style } from '../markup/index.ts';
+
+import { getCardColors, isPrefixedHexColor } from './color.ts';
+import { SECONDARY_ERROR_MESSAGES, TRY_AGAIN_LATER } from './error.ts';
+import { kFormatter } from './fmt.ts';
+import { clampValue } from './ops.ts';
 
 /**
  * Auto layout utility, allows us to layout things vertically or horizontally with
  * proper gaping.
  *
- * The caller must ensure that the passed `items` are properly sanitized!
- *
- * @param props Function properties.
- * @param props.items Array of sanitized items to layout.
- * @param props.gap Gap between items.
- * @param props.direction Direction to layout items.
- * @param props.sizes Array of sizes for each item.
- * @returns Array of items with proper layout.
+ * @returns The items, each in the group that positions it.
  */
 const flexLayout = ({
   items,
@@ -23,59 +18,60 @@ const flexLayout = ({
   direction,
   sizes = [],
 }: {
-  items: Array<string>;
+  items: Array<Child>;
   gap: number;
   direction?: 'column' | 'row';
   sizes?: Array<number>;
-}): Array<string> => {
+}): Array<Child> => {
   if (sizes.some((size) => !Number.isFinite(size))) {
     throw new Error('flexLayout: `sizes` must contain only numbers');
   }
 
+  const laidOut = items.filter(Boolean);
+
+  // A lone item is already where it belongs, so it needs no group to move it.
+  if (laidOut.length === 1) {
+    return laidOut;
+  }
+
   let lastSize = 0;
-  // filter() for filtering out empty strings
-  return items.filter(Boolean).map((item, i) => {
-    const size = sizes[i] || 0;
-    let transform = `translate(${lastSize}, 0)`;
-    if (direction === 'column') {
-      transform = `translate(0, ${lastSize})`;
-    }
-    lastSize += size + gap;
-    return `<g transform="${transform}">${item}</g>`;
+  return laidOut.map((item, i) => {
+    const offset = lastSize;
+    lastSize += (sizes[i] ?? 0) + gap;
+
+    // The first item never moves, so it gets no transform to carry.
+    const transform =
+      offset === 0
+        ? undefined
+        : direction === 'column'
+          ? `translate(0, ${offset})`
+          : `translate(${offset}, 0)`;
+
+    return el('g', { transform }, item);
   });
 };
 
 /**
  * Creates a node to display the primary programming language of the repository/gist.
  *
- * @param langName Language name.
- * @param langColor Language color.
  * @returns Language display SVG object.
  */
-const createLanguageNode = (langName: string, langColor: string): string => {
+const createLanguageNode = (langName: string, langColor: string): MarkupElement => {
   if (!isPrefixedHexColor(langColor)) {
     throw new Error(`Invalid language color: "${langColor}"`);
   }
 
-  return `
-    <g data-testid="primary-lang">
-      <circle data-testid="lang-color" cx="0" cy="-5" r="6" fill="${langColor}" />
-      <text data-testid="lang-name" class="gray" x="15">${encodeHTML(langName)}</text>
-    </g>
-    `;
+  return el(
+    'g',
+    { 'data-testid': 'primary-lang' },
+    el('circle', { 'data-testid': 'lang-color', cx: 0, cy: -5, r: 6, fill: langColor }),
+    el('text', { 'data-testid': 'lang-name', class: 'gray', x: 15 }, langName),
+  );
 };
 
 /**
  * Create a node to indicate progress in percentage along a horizontal line.
  *
- * @param params Object that contains the createProgressNode parameters.
- * @param params.x X-axis position.
- * @param params.y Y-axis position.
- * @param params.width Width of progress bar.
- * @param params.color Optional foreground color as an inline fill fallback.
- *   When omitted, the color must be set via a `.lang-progress` CSS rule.
- * @param params.progress Progress value.
- * @param params.delay Delay before animation starts.
  * @returns Progress node.
  */
 const createProgressNode = ({
@@ -89,42 +85,57 @@ const createProgressNode = ({
   x: number;
   y: number;
   width: number;
+  /** When omitted, the color must be set via a `.lang-progress` CSS rule. */
   color?: string;
   progress: number;
   delay: number;
-}): string => {
+}): MarkupElement => {
   if (color !== undefined && !isPrefixedHexColor(color)) {
     throw new Error(`Invalid progress color: "${color}"`);
   }
   if (!Number.isFinite(width)) {
-    throw new Error(`Invalid width: "${width}"`);
+    throw new TypeError(`Invalid width: "${width}"`);
   }
   if (!Number.isFinite(x)) {
-    throw new Error(`Invalid x: "${x}"`);
+    throw new TypeError(`Invalid x: "${x}"`);
   }
   if (!Number.isFinite(y)) {
-    throw new Error(`Invalid y: "${y}"`);
+    throw new TypeError(`Invalid y: "${y}"`);
   }
   if (!Number.isFinite(delay)) {
-    throw new Error(`Invalid delay: "${delay}"`);
+    throw new TypeError(`Invalid delay: "${delay}"`);
   }
 
   const progressPercentage = clampValue(progress, 2, 100);
 
-  return `
-    <svg width="${width}" x="${x}" y="${y}">
-      <rect data-testid="progress-background" class="progress-background" rx="5" ry="5" x="0" y="0" width="${width}" height="8"></rect>
-      <svg data-testid="lang-progress" width="${progressPercentage}%">
-        <rect
-            height="8"
-            ${color === undefined ? '' : `fill="${color}"`}
-            rx="5" ry="5" x="0" y="0"
-            class="lang-progress"
-            style="animation-delay: ${delay}ms;"
-        />
-      </svg>
-    </svg>
-  `;
+  return el(
+    'svg',
+    { width, x, y },
+    el('rect', {
+      'data-testid': 'progress-background',
+      class: 'progress-background',
+      rx: 5,
+      ry: 5,
+      x: 0,
+      y: 0,
+      width,
+      height: 8,
+    }),
+    el(
+      'svg',
+      { 'data-testid': 'lang-progress', width: `${progressPercentage}%` },
+      el('rect', {
+        height: 8,
+        fill: color,
+        rx: 5,
+        ry: 5,
+        x: 0,
+        y: 0,
+        class: 'lang-progress',
+        style: `animation-delay: ${delay}ms;`,
+      }),
+    ),
+  );
 };
 
 /**
@@ -132,15 +143,6 @@ const createProgressNode = ({
  * native, font-aware wrapping. Content overflowing `lineCount` lines is
  * clipped (with an ellipsis on the last visible line) by CSS line-clamp.
  *
- * @param props Function properties.
- * @param props.text Text to render (will be HTML-encoded).
- * @param props.x X position of the foreignObject.
- * @param props.y Y position of the foreignObject.
- * @param props.width Width of the wrap box.
- * @param props.height Height of the wrap box.
- * @param props.lineCount Maximum number of lines to display.
- * @param props.className CSS class applied to the inner element.
- * @param props.testId Optional test id for the inner element.
  * @returns foreignObject SVG node.
  */
 const wrappedTextNode = ({
@@ -161,31 +163,37 @@ const wrappedTextNode = ({
   lineCount: number;
   className: string;
   testId?: string;
-}): string => {
+}): MarkupElement => {
   if (!Number.isFinite(x)) {
-    throw new Error(`Invalid x: "${x}"`);
+    throw new TypeError(`Invalid x: "${x}"`);
   }
   if (!Number.isFinite(y)) {
-    throw new Error(`Invalid y: "${y}"`);
+    throw new TypeError(`Invalid y: "${y}"`);
   }
   if (!Number.isFinite(width)) {
-    throw new Error(`Invalid width: "${width}"`);
+    throw new TypeError(`Invalid width: "${width}"`);
   }
   if (!Number.isFinite(height)) {
-    throw new Error(`Invalid height: "${height}"`);
+    throw new TypeError(`Invalid height: "${height}"`);
   }
   if (!Number.isFinite(lineCount)) {
-    throw new Error(`Invalid lineCount: "${lineCount}"`);
+    throw new TypeError(`Invalid lineCount: "${lineCount}"`);
   }
 
-  const testIdAttr = testId ? ` data-testid="${encodeHTML(testId)}"` : '';
-  return `
-    <foreignObject x="${x}" y="${y}" width="${width}" height="${height}">
-      <div xmlns="http://www.w3.org/1999/xhtml" class="${encodeHTML(className)}" style="--lines: ${lineCount};"${testIdAttr}>${encodeHTML(
-        text,
-      )}</div>
-    </foreignObject>
-  `;
+  return el(
+    'foreignObject',
+    { x, y, width, height },
+    el(
+      'div',
+      {
+        xmlns: 'http://www.w3.org/1999/xhtml',
+        class: className,
+        style: `--lines: ${lineCount};`,
+        'data-testid': testId,
+      },
+      text,
+    ),
+  );
 };
 
 /**
@@ -194,69 +202,67 @@ const wrappedTextNode = ({
  * browser handles wrapping and the line count is taken from the `--lines`
  * custom property set on the element.
  *
- * @param color Text color (CSS `color` property).
- * @returns CSS rules block (without the surrounding selector).
+ * @returns The declarations, to merge into the class's own rule.
  */
-const wrappedTextStyles = (color: string): string => {
+const wrappedTextStyles = (color: string): Declarations => {
   if (!isPrefixedHexColor(color)) {
     throw new Error(`Invalid text color: "${color}"`);
   }
 
-  return `
-      color: ${color};
-      margin: 0;
-      line-height: 1.2;
-      overflow-wrap: anywhere;
-      word-break: break-word;
-      display: -webkit-box;
-      -webkit-box-orient: vertical;
-      -webkit-line-clamp: var(--lines);
-      line-clamp: var(--lines);
-      overflow: hidden;
-      text-overflow: ellipsis;
-      padding-bottom: 0.15em;
-  `;
+  return {
+    color,
+    margin: 0,
+    'line-height': 1.2,
+    'overflow-wrap': 'anywhere',
+    'word-break': 'break-word',
+    display: '-webkit-box',
+    '-webkit-box-orient': 'vertical',
+    '-webkit-line-clamp': 'var(--lines)',
+    'line-clamp': 'var(--lines)',
+    overflow: 'hidden',
+    'text-overflow': 'ellipsis',
+    'padding-bottom': '0.15em',
+  };
 };
 
 /**
  * Creates an icon with label to display repository/gist stats like forks, stars, etc.
+ * Draws nothing when the label is not positive.
  *
- * The caller must ensure that the passed `icon` is properly sanitized!
- *
- * @param icon The sanitized icon to display.
- * @param label The label to display.
- * @param testid The testid to assign to the label.
- * @param iconSize The size of the icon.
- * @returns Icon with label SVG object.
+ * @returns Icon with label SVG object, or nothing when the label is not positive.
  */
 const iconWithLabel = (
-  icon: string,
+  icon: Child,
   label: number | string,
   testid: string,
   iconSize: number,
-): string => {
+): Child => {
   if (typeof label === 'number' && label <= 0) {
-    return '';
+    return undefined;
   }
 
   if (!Number.isFinite(iconSize)) {
-    throw new Error(`Invalid iconSize: "${iconSize}"`);
+    throw new TypeError(`Invalid iconSize: "${iconSize}"`);
   }
 
-  const iconSvg = `
-      <svg
-        class="icon"
-        y="-12"
-        viewBox="0 0 16 16"
-        version="1.1"
-        width="${iconSize}"
-        height="${iconSize}"
-      >
-        ${icon}
-      </svg>
-    `;
-  const text = `<text data-testid="${encodeHTML(testid)}" class="gray">${encodeHTML(String(label))}</text>`;
-  return flexLayout({ items: [iconSvg, text], gap: 20 }).join('');
+  return flexLayout({
+    items: [
+      el(
+        'svg',
+        {
+          class: 'icon',
+          y: -12,
+          viewBox: '0 0 16 16',
+          version: '1.1',
+          width: iconSize,
+          height: iconSize,
+        },
+        icon,
+      ),
+      el('text', { 'data-testid': testid, class: 'gray' }, String(label)),
+    ],
+    gap: 20,
+  });
 };
 
 /**
@@ -264,22 +270,8 @@ const iconWithLabel = (
  * (a label and its value, optionally with an icon and link).
  * Shared by the stats and repo cards.
  *
- * The caller must ensure that the passed `icon` and `link` are properly sanitized!
+ * The caller must ensure that the passed `link` is properly sanitized!
  *
- * @param params Object that contains the createTextNode parameters.
- * @param params.icon The sanitized icon to display.
- * @param params.label The label to display.
- * @param params.value The value to display.
- * @param params.id The id of the stat.
- * @param params.unitSymbol The unit symbol of the stat.
- * @param params.index The index of the stat.
- * @param params.showIcons Whether to show icons.
- * @param params.shiftValuePos Number of pixels the value has to be shifted to the right.
- * @param params.bold Whether to bold the label.
- * @param params.numberFormat The format of numbers on card.
- * @param params.numberPrecision The precision of numbers on card.
- * @param params.link Sanitized url to link to.
- * @param params.labelXOffset horizontal offset for label.
  * @returns The stats card text item SVG object.
  */
 const createTextNode = ({
@@ -291,13 +283,15 @@ const createTextNode = ({
   index,
   showIcons,
   shiftValuePos,
+  valueAnchorX,
   bold,
+  labelBold = bold,
   numberFormat,
   numberPrecision,
   link,
   labelXOffset = 25,
 }: {
-  icon: string;
+  icon: Child;
   label: string;
   value: number | string;
   id: string;
@@ -306,20 +300,25 @@ const createTextNode = ({
   index: number;
   showIcons: boolean;
   shiftValuePos: number;
+  valueAnchorX?: number | undefined;
   bold: boolean;
+  labelBold?: boolean;
   numberFormat: string;
   numberPrecision?: number | undefined;
   link?: string | undefined;
   labelXOffset?: number;
-}): string => {
+}): MarkupElement => {
   if (!Number.isFinite(labelXOffset)) {
-    throw new Error(`Invalid labelXOffset: "${labelXOffset}"`);
+    throw new TypeError(`Invalid labelXOffset: "${labelXOffset}"`);
   }
   if (!Number.isFinite(shiftValuePos)) {
-    throw new Error(`Invalid shiftValuePos: "${shiftValuePos}"`);
+    throw new TypeError(`Invalid shiftValuePos: "${shiftValuePos}"`);
   }
   if (!Number.isFinite(index)) {
-    throw new Error(`Invalid index: "${index}"`);
+    throw new TypeError(`Invalid index: "${index}"`);
+  }
+  if (valueAnchorX !== undefined && !Number.isFinite(valueAnchorX)) {
+    throw new Error(`Invalid valueAnchorX: "${valueAnchorX}"`);
   }
 
   const precision =
@@ -331,54 +330,62 @@ const createTextNode = ({
   const rawValue = numberFormat.toLowerCase() === 'long' || id === 'prs_merged_percentage';
   const kValue = rawValue || typeof value !== 'number' ? value : kFormatter(value, precision);
 
-  const staggerDelay = (index + 3) * 150;
-  const boldClass = bold ? ' bold' : 'not_bold';
+  const staggerDelay = 120 + index * 40;
+  const boldClass = bold ? 'bold' : 'not_bold';
+  const labelBoldClass = labelBold ? 'bold' : 'not_bold';
   const valueX = (showIcons ? 140 : 120) + (bold ? 5 : 0) + shiftValuePos;
   const unit = unitSymbol ? ` ${unitSymbol}` : '';
-  const labelOffset = showIcons ? `x="${labelXOffset}"` : '';
-  const iconSvg = showIcons
-    ? `
-    <svg data-testid="icon" class="icon" viewBox="0 0 16 16" version="1.1" width="16" height="16">
-      ${icon}
-    </svg>
-  `
-    : '';
-
-  const content = `
-      ${iconSvg}
-      <text class="stat ${boldClass}" ${labelOffset} y="12.5">${encodeHTML(label)}:</text>
-      <text
-        class="stat ${boldClass}"
-        x="${valueX}"
-        y="12.5"
-        data-testid="${id}"
-      >${kValue}${unit}</text>`;
-  const inner = link ? `<a href="${link}">${content}</a>` : content;
-
-  return `
-    <g class="stagger" style="animation-delay: ${staggerDelay}ms" transform="translate(25, 0)">${inner}
-    </g>
-  `;
+
+  const content = [
+    showIcons &&
+      el(
+        'svg',
+        {
+          'data-testid': 'icon',
+          class: 'icon',
+          viewBox: '0 0 16 16',
+          version: '1.1',
+          width: 16,
+          height: 16,
+        },
+        icon,
+      ),
+    el(
+      'text',
+      { class: `stat ${labelBoldClass}`, x: showIcons ? labelXOffset : undefined, y: 12.5 },
+      `${label}:`,
+    ),
+    el(
+      'text',
+      {
+        class: `stat ${boldClass}`,
+        x: valueAnchorX ?? valueX,
+        'text-anchor': valueAnchorX === undefined ? undefined : 'end',
+        y: 12.5,
+        'data-testid': id,
+      },
+      `${String(kValue)}${unit}`,
+    ),
+  ];
+
+  return el(
+    'g',
+    {
+      class: 'stagger',
+      style: `animation-delay: ${staggerDelay}ms`,
+      transform: 'translate(25, 0)',
+    },
+    link ? el('a', { href: link }, content) : content,
+  );
 };
 
-// Script parameters.
 const ERROR_CARD_LENGTH = 576.5;
 
-const UPSTREAM_API_ERRORS = [TRY_AGAIN_LATER, SECONDARY_ERROR_MESSAGES.rate_limited];
+const UPSTREAM_API_ERRORS = new Set([TRY_AGAIN_LATER, SECONDARY_ERROR_MESSAGES.rate_limited]);
 
 /**
  * Renders error message on the card.
  *
- * @param args Function arguments.
- * @param args.message Main error message.
- * @param args.secondaryMessage The secondary error message.
- * @param args.renderOptions Render options.
- * @param args.renderOptions.title_color Card title color.
- * @param args.renderOptions.text_color Card text color.
- * @param args.renderOptions.bg_color Card background color.
- * @param args.renderOptions.border_color Card border color.
- * @param args.renderOptions.theme Card theme.
- * @param args.renderOptions.show_repo_link Whether to show repo link or not.
  * @returns The SVG markup.
  */
 const renderError = ({
@@ -417,37 +424,55 @@ const renderError = ({
     theme,
   });
 
-  return `
-    <svg width="${ERROR_CARD_LENGTH}"  height="120" viewBox="0 0 ${ERROR_CARD_LENGTH} 120" fill="${String(bgColor)}" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="titleId descId">
-    <title id="titleId">${encodeHTML(message)}</title>
-    <desc id="descId">${encodeHTML(secondaryMessage)}</desc>
-    <style>
-    .text { font: 600 16px 'Segoe UI', Ubuntu, Sans-Serif; fill: ${titleColor} }
-    .small { font: 600 12px 'Segoe UI', Ubuntu, Sans-Serif; fill: ${textColor} }
-    .gray { fill: #858585 }
-    </style>
-    <rect x="0.5" y="0.5" width="${
-      ERROR_CARD_LENGTH - 1
-    }" height="99%" rx="4.5" fill="${String(bgColor)}" stroke="${borderColor}"/>
-    <text x="25" y="45" class="text">Something went wrong!${
-      UPSTREAM_API_ERRORS.includes(secondaryMessage) || !show_repo_link
-        ? ''
-        : ' file an issue at https://tinyurl.com/github-stats'
-    }</text>
-    <text data-testid="message" x="25" y="55" class="text small">
-      <tspan x="25" dy="18">${encodeHTML(message)}</tspan>
-      <tspan x="25" dy="18" class="gray">${encodeHTML(secondaryMessage)}</tspan>
-    </text>
-    </svg>
-  `;
+  const hint =
+    UPSTREAM_API_ERRORS.has(secondaryMessage) || !show_repo_link
+      ? ''
+      : ' file an issue at https://tinyurl.com/github-stats';
+
+  return renderMarkup(
+    el(
+      'svg',
+      {
+        width: ERROR_CARD_LENGTH,
+        height: 120,
+        viewBox: `0 0 ${ERROR_CARD_LENGTH} 120`,
+        fill: String(bgColor),
+        xmlns: 'http://www.w3.org/2000/svg',
+        role: 'img',
+        'aria-labelledby': 'titleId descId',
+      },
+      el('title', { id: 'titleId' }, message),
+      el('desc', { id: 'descId' }, secondaryMessage),
+      style(
+        rule('.text', { font: "600 16px 'Segoe UI', Ubuntu, Sans-Serif", fill: titleColor }),
+        rule('.small', { font: "600 12px 'Segoe UI', Ubuntu, Sans-Serif", fill: textColor }),
+        rule('.gray', { fill: '#858585' }),
+      ),
+      el('rect', {
+        x: 0.5,
+        y: 0.5,
+        width: ERROR_CARD_LENGTH - 1,
+        height: '99%',
+        rx: 8,
+        fill: String(bgColor),
+        stroke: borderColor,
+      }),
+      el('text', { x: 25, y: 45, class: 'text' }, `Something went wrong!${hint}`),
+      el(
+        'text',
+        { 'data-testid': 'message', x: 25, y: 55, class: 'text small' },
+        el('tspan', { x: 25, dy: 18 }, message),
+        el('tspan', { x: 25, dy: 18, class: 'gray' }, secondaryMessage),
+      ),
+    ),
+  );
 };
 
 /**
  * Retrieve text length based on Segoe UI font.
  *
  * @see https://stackoverflow.com/a/48172630/10629172
- * @param str String to measure.
- * @param fontSize Font size.
+ *
  * @returns Text length.
  */
 const measureText = (str: string, fontSize = 10): number => {
@@ -494,18 +519,17 @@ const measureText = (str: string, fontSize = 10): number => {
   const cjkRange = /[\u3000-\u9FFF\uFF00-\uFFEF]/;
 
   return (
-    str
-      .split('')
-      .map((c) => {
-        if (cjkRange.test(c) || c === '\u3000') {
+    [...str]
+      .map((char) => {
+        if (cjkRange.test(char) || char === '\u3000') {
           // CJK glyphs and U+3000 IDEOGRAPHIC SPACE are full-width by default;
           return 1;
         }
-        if (c.charCodeAt(0) < widths.length) {
-          return widths[c.charCodeAt(0)] ?? avg;
-        } else {
-          return avg;
+        const code = char.codePointAt(0) ?? 0;
+        if (code < widths.length) {
+          return widths[code] ?? avg;
         }
+        return avg;
       })
       .reduce((cur, acc) => acc + cur) * fontSize
   );
@@ -518,9 +542,6 @@ const measureText = (str: string, fontSize = 10): number => {
  * The browser still does the real wrap inside the foreignObject; this is only
  * used to size the SVG.
  *
- * @param text Text to split.
- * @param fontSize Font size in px (matches `measureText`).
- * @param maxWidth Available wrap width in px.
  * @returns Estimated wrapped lines.
  */
 const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Array<string> => {
@@ -538,7 +559,7 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
   // Korean Hangul (U+AC00–U+D7AF) is intentionally NOT in the CJK range
   // because Korean wraps at word boundaries by default in HTML.
   // ASCII whitespace is collapsed to a single space per CSS `white-space: normal;`
-  const normalizedText = text.replace(/[\t\n\r ]+/g, ' ');
+  const normalizedText = text.replaceAll(/[\t\n\r ]+/g, ' ');
   const tokens = normalizedText.match(
     /\s|[\u3000-\u9FFF\uFF00-\uFFEF]|[^\s\u3000-\u9FFF\uFF00-\uFFEF]+/g,
   );
@@ -546,8 +567,11 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
     return [];
   }
 
-  const takeFittingSegment = (token: string, availableWidth: number) => {
-    const characters = token.split('');
+  const takeFittingSegment = (
+    token: string,
+    availableWidth: number,
+  ): { segment: string; width: number } => {
+    const characters = [...token];
     let segment = '';
     let width = 0;
 
@@ -575,7 +599,7 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
       if (currentWidth === 0) {
         continue;
       }
-      lines[lines.length - 1] = (lines[lines.length - 1] ?? '') + token;
+      lines[lines.length - 1] = (lines.at(-1) ?? '') + token;
       currentWidth += measureText(token, fontSize);
       continue;
     }
@@ -585,7 +609,7 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
     while (remaining) {
       const w = measureText(remaining, fontSize);
       if (currentWidth + w <= maxWidth) {
-        lines[lines.length - 1] = (lines[lines.length - 1] ?? '') + remaining;
+        lines[lines.length - 1] = (lines.at(-1) ?? '') + remaining;
         currentWidth += w;
         break;
       }
@@ -598,7 +622,7 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
 
       // An atom wider than the box wraps mid-glyph (overflow-wrap: anywhere).
       const { segment, width } = takeFittingSegment(remaining, maxWidth);
-      lines[lines.length - 1] = (lines[lines.length - 1] ?? '') + segment;
+      lines[lines.length - 1] = (lines.at(-1) ?? '') + segment;
       currentWidth = width;
       remaining = remaining.slice(segment.length);
     }
@@ -607,14 +631,38 @@ const splitWrappedText = (text: string, fontSize: number, maxWidth: number): Arr
   return lines.map((line) => line.replace(/[\t\n\r ]+$/, ''));
 };
 
+/**
+ * Split text over multiple lines based on the card width.
+ *
+ * @returns Array of lines.
+ */
+const wrapTextMultiline = (
+  text: string,
+  width: number,
+  fontSize: number,
+  maxLines = 3,
+): Array<string> => {
+  const wrapped = splitWrappedText(text, fontSize, width);
+  const lines = wrapped.map((line) => line.trim()).slice(0, maxLines); // Only consider maxLines lines
+
+  // Add "..." to the last line if the text exceeds maxLines
+  if (wrapped.length > maxLines) {
+    const lastIndex = maxLines - 1;
+    const lastLine = lines[lastIndex];
+    if (lastLine !== undefined) {
+      lines[lastIndex] = `${lastLine}...`;
+    }
+  }
+
+  // Remove empty lines if text fits in less than maxLines lines
+  const multiLineText = lines.filter(Boolean);
+  return multiLineText;
+};
+
 /**
  * Estimate how many lines a string will wrap to when laid out greedily at the
  * given font size inside a box of width `maxWidth`, capped at `maxLines`.
  *
- * @param text Text to estimate.
- * @param fontSize Font size in px (matches `measureText`).
- * @param maxWidth Available wrap width in px.
- * @param maxLines Cap on the returned line count.
  * @returns Estimated line count, at least 1, at most `maxLines`.
  */
 const countWrappedLines = (
@@ -622,9 +670,7 @@ const countWrappedLines = (
   fontSize: number,
   maxWidth: number,
   maxLines: number,
-): number => {
-  return Math.min(Math.max(1, splitWrappedText(text, fontSize, maxWidth).length), maxLines);
-};
+): number => Math.min(Math.max(1, splitWrappedText(text, fontSize, maxWidth).length), maxLines);
 
 export {
   renderError,
@@ -635,6 +681,7 @@ export {
   flexLayout,
   measureText,
   splitWrappedText,
+  wrapTextMultiline,
   countWrappedLines,
   wrappedTextNode,
   wrappedTextStyles,