@stats-forge/github-stats-forge-core 0.0.2 → 0.2.0

package/src/cards/top-languages.ts

@@ -1,17 +1,19 @@
-import { Card } from '../common/Card.js';
-import { getLightDarkColors, isPrefixedHexColor } from '../common/color.js';
-import { formatBytes } from '../common/fmt.js';
-import { encodeHTML } from '../common/html.js';
-import { I18n } from '../common/I18n.js';
-import { DEFAULT_LANG_COLOR } from '../common/languageColors.js';
-import { chunkArray, clampValue, lowercaseTrim } from '../common/ops.js';
-import { createProgressNode, flexLayout, measureText } from '../common/render.js';
-import type { Lang, TopLangData } from '../fetchers/types.js';
-import { langCardLocales } from '../translations.js';
-
-import type { CardOptions, CommonCardOptions } from './options.js';
-
-const DEFAULT_CARD_WIDTH = 300;
+import { CARD_ICON, CARD_WIDTH, FONT_WEIGHT, firefoxFontSize, font } from '../common/brand.ts';
+import { Card } from '../common/Card.ts';
+import { getLightDarkColors, isPrefixedHexColor } from '../common/color.ts';
+import { formatBytes } from '../common/fmt.ts';
+import { I18n } from '../common/I18n.ts';
+import { DEFAULT_LANG_COLOR } from '../common/languageColors.ts';
+import { chunkArray, clampValue, lowercaseTrim } from '../common/ops.ts';
+import { createProgressNode, flexLayout, measureText } from '../common/render.ts';
+import type { Lang, TopLangData } from '../fetchers/types.ts';
+import type { Child, MarkupElement } from '../markup/index.ts';
+import { atRule, el, rule } from '../markup/index.ts';
+import { langCardLocales } from '../translations.ts';
+
+import type { CardOptions, CommonCardOptions } from './options.ts';
+
+const DEFAULT_CARD_WIDTH = CARD_WIDTH.compact;
 const MIN_CARD_WIDTH = 280;
 const CARD_PADDING = 25;
 const COMPACT_LAYOUT_BASE_HEIGHT = 90;
@@ -20,6 +22,8 @@ const MAXIMUM_LANGS_COUNT = 20;
 const NORMAL_LAYOUT_DEFAULT_LANGS_COUNT = 5;
 const COMPACT_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 const DONUT_LAYOUT_DEFAULT_LANGS_COUNT = 5;
+/** Room for the chart that sits beside the language list. */
+const DONUT_EXTRA_WIDTH = 50;
 const PIE_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 const DONUT_VERTICAL_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 
@@ -49,38 +53,35 @@ interface TopLangOptions extends CommonCardOptions {
 /**
  * Retrieves the programming language whose name is the longest.
  *
- * @param arr Array of programming languages.
  * @returns Longest programming language object.
  */
-const getLongestLang = (arr: Array<Lang>): Pick<Lang, 'name' | 'size' | 'color'> =>
-  arr.reduce<Pick<Lang, 'name' | 'size' | 'color'>>(
-    (savedLang, lang) => (lang.name.length > savedLang.name.length ? lang : savedLang),
-    { name: '', size: 0, color: '' },
-  );
+const getLongestLang = (arr: Array<Lang>): Pick<Lang, 'name' | 'size' | 'color'> => {
+  let longest: Pick<Lang, 'name' | 'size' | 'color'> = { name: '', size: 0, color: '' };
+  for (const lang of arr) {
+    if (lang.name.length > longest.name.length) {
+      longest = lang;
+    }
+  }
+  return longest;
+};
 
 /**
  * Convert degrees to radians.
  *
- * @param angleInDegrees Angle in degrees.
  * @returns Angle in radians.
  */
-const degreesToRadians = (angleInDegrees: number): number => angleInDegrees * (Math.PI / 180.0);
+const degreesToRadians = (angleInDegrees: number): number => angleInDegrees * (Math.PI / 180);
 
 /**
  * Convert radians to degrees.
  *
- * @param angleInRadians Angle in radians.
  * @returns Angle in degrees.
  */
-const radiansToDegrees = (angleInRadians: number): number => angleInRadians / (Math.PI / 180.0);
+const radiansToDegrees = (angleInRadians: number): number => angleInRadians / (Math.PI / 180);
 
 /**
  * Convert polar coordinates to cartesian coordinates.
  *
- * @param centerX Center x coordinate.
- * @param centerY Center y coordinate.
- * @param radius Radius of the circle.
- * @param angleInDegrees Angle in degrees.
  * @returns Cartesian coordinates.
  */
 const polarToCartesian = (
@@ -99,10 +100,6 @@ const polarToCartesian = (
 /**
  * Convert cartesian coordinates to polar coordinates.
  *
- * @param centerX Center x coordinate.
- * @param centerY Center y coordinate.
- * @param x Point x coordinate.
- * @param y Point y coordinate.
  * @returns Polar coordinates.
  */
 const cartesianToPolar = (
@@ -111,7 +108,7 @@ const cartesianToPolar = (
   x: number,
   y: number,
 ): { radius: number; angleInDegrees: number } => {
-  const radius = Math.sqrt(Math.pow(x - centerX, 2) + Math.pow(y - centerY, 2));
+  const radius = Math.hypot(x - centerX, y - centerY);
   let angleInDegrees = radiansToDegrees(Math.atan2(y - centerY, x - centerX));
   if (angleInDegrees < 0) {
     angleInDegrees += 360;
@@ -122,79 +119,60 @@ const cartesianToPolar = (
 /**
  * Calculates length of circle.
  *
- * @param radius Radius of the circle.
  * @returns The length of the circle.
  */
-const getCircleLength = (radius: number): number => {
-  return 2 * Math.PI * radius;
-};
+const getCircleLength = (radius: number): number => 2 * Math.PI * radius;
 
 /**
  * Calculates height for the compact layout.
  *
- * @param totalLangs Total number of languages.
  * @returns Card height.
  */
-const calculateCompactLayoutHeight = (totalLangs: number): number => {
-  return COMPACT_LAYOUT_BASE_HEIGHT + Math.round(totalLangs / 2) * 25;
-};
+const calculateCompactLayoutHeight = (totalLangs: number): number =>
+  COMPACT_LAYOUT_BASE_HEIGHT + Math.round(totalLangs / 2) * 25;
 
 /**
  * Calculates height for the normal layout.
  *
- * @param totalLangs Total number of languages.
  * @returns Card height.
  */
-const calculateNormalLayoutHeight = (totalLangs: number): number => {
-  return 45 + (totalLangs + 1) * 40;
-};
+const calculateNormalLayoutHeight = (totalLangs: number): number => 45 + (totalLangs + 1) * 40;
 
 /**
  * Calculates height for the donut layout.
  *
- * @param totalLangs Total number of languages.
  * @returns Card height.
  */
-const calculateDonutLayoutHeight = (totalLangs: number): number => {
-  return 215 + Math.max(totalLangs - 5, 0) * 32;
-};
+const calculateDonutLayoutHeight = (totalLangs: number): number =>
+  215 + Math.max(totalLangs - 5, 0) * 32;
 
 /**
  * Calculates height for the donut vertical layout.
  *
- * @param totalLangs Total number of languages.
  * @returns Card height.
  */
-const calculateDonutVerticalLayoutHeight = (totalLangs: number): number => {
-  return 300 + Math.round(totalLangs / 2) * 25;
-};
+const calculateDonutVerticalLayoutHeight = (totalLangs: number): number =>
+  300 + Math.round(totalLangs / 2) * 25;
 
 /**
  * Calculates height for the pie layout.
  *
- * @param totalLangs Total number of languages.
  * @returns Card height.
  */
-const calculatePieLayoutHeight = (totalLangs: number): number => {
-  return 300 + Math.round(totalLangs / 2) * 25;
-};
+const calculatePieLayoutHeight = (totalLangs: number): number =>
+  300 + Math.round(totalLangs / 2) * 25;
 
 /**
  * Calculates the center translation needed to keep the donut chart centred.
  *
- * @param totalLangs Total number of languages.
  * @returns Donut center translation.
  */
-const donutCenterTranslation = (totalLangs: number): number => {
-  return -45 + Math.max(totalLangs - 5, 0) * 16;
-};
+const donutCenterTranslation = (totalLangs: number): number =>
+  -45 + Math.max(totalLangs - 5, 0) * 16;
 
 /**
  * Trim top languages to lang_count while also hiding certain languages.
  *
- * @param topLangs Top languages.
- * @param langs_count Number of languages to show.
- * @param hide Languages to hide.
  * @returns Trimmed top languages and total size.
  */
 const trimTopLanguages = (
@@ -208,14 +186,14 @@ const trimTopLanguages = (
 
   // populate langsToHide map for quick lookup while filtering out
   if (hide) {
-    hide.forEach((langName) => {
+    for (const langName of hide) {
       langsToHide[lowercaseTrim(langName)] = true;
-    });
+    }
   }
 
   // filter out languages to be hidden
   langs = langs
-    .sort((a, b) => b.size - a.size)
+    .toSorted((a, b) => b.size - a.size)
     .filter((lang) => !langsToHide[lowercaseTrim(lang.name)])
     .slice(0, langsCount);
 
@@ -227,20 +205,15 @@ const trimTopLanguages = (
 /**
  * Get display value corresponding to the format.
  *
- * @param size Bytes size.
- * @param percentages Percentage value.
- * @param format Format of the stats.
  * @returns Display value.
  */
-const getDisplayValue = (size: number, percentages: number, format: string): string => {
-  return format === 'bytes' ? formatBytes(size) : `${percentages.toFixed(2)}%`;
-};
+const getDisplayValue = (size: number, percentages: number, format: string): string =>
+  format === 'bytes' ? formatBytes(size) : `${percentages.toFixed(2)}%`;
 
 /**
  * Resolves a language's display color, falling back to the default, and
  * validates it is a prefixed hex color.
  *
- * @param lang Programming language object.
  * @returns Validated language color.
  */
 const resolveLangColor = (lang: Lang): string => {
@@ -254,15 +227,6 @@ const resolveLangColor = (lang: Lang): string => {
 /**
  * Create progress bar text item for a programming language.
  *
- * @param props Function properties.
- * @param props.width The card width
- * @param props.color Color of the programming language.
- * @param props.name Name of the programming language.
- * @param props.size Size of the programming language.
- * @param props.totalSize Total size of all languages.
- * @param props.statsFormat Stats format.
- * @param props.hideValues Whether to hide stats values.
- * @param props.index Index of the programming language.
  * @returns Programming language SVG node.
  */
 const createProgressTextNode = ({
@@ -283,7 +247,7 @@ const createProgressTextNode = ({
   statsFormat: string;
   hideValues?: boolean | undefined;
   index: number;
-}): string => {
+}): MarkupElement => {
   const staggerDelay = (index + 3) * 150;
   const paddingRight = hideValues ? CARD_PADDING * 2 : 95;
   const progressTextX = width - paddingRight + 10;
@@ -292,32 +256,25 @@ const createProgressTextNode = ({
   const progress = (size / totalSize) * 100;
   const displayValue = getDisplayValue(size, progress, statsFormat);
 
-  return `
-    <g class="stagger" style="animation-delay: ${staggerDelay}ms">
-      <text data-testid="lang-name" x="2" y="15" class="lang-name">${encodeHTML(name)}</text>
-      ${hideValues ? '' : `<text x="${progressTextX}" y="34" class="lang-name">${encodeHTML(displayValue)}</text>`}
-      ${createProgressNode({
-        x: 0,
-        y: 25,
-        color,
-        width: progressWidth,
-        progress,
-        delay: staggerDelay + 300,
-      })}
-    </g>
-  `;
+  return el(
+    'g',
+    { class: 'stagger', style: `animation-delay: ${staggerDelay}ms` },
+    el('text', { 'data-testid': 'lang-name', x: 2, y: 15, class: 'lang-name' }, name),
+    !hideValues && el('text', { x: progressTextX, y: 34, class: 'lang-name' }, displayValue),
+    createProgressNode({
+      x: 0,
+      y: 25,
+      color,
+      width: progressWidth,
+      progress,
+      delay: staggerDelay + 300,
+    }),
+  );
 };
 
 /**
  * Creates compact text item for a programming language.
  *
- * @param props Function properties.
- * @param props.lang Programming language object.
- * @param props.totalSize Total size of all languages.
- * @param props.hideProgress Whether to hide percentage.
- * @param props.hideValues Whether to hide stats values (percentages/bytes).
- * @param props.statsFormat Stats format
- * @param props.index Index of the programming language.
  * @returns Compact layout programming language SVG node.
  */
 const createCompactLangNode = ({
@@ -334,32 +291,26 @@ const createCompactLangNode = ({
   hideValues?: boolean | undefined;
   statsFormat?: string | undefined;
   index: number;
-}): string => {
+}): MarkupElement => {
   const percentages = (lang.size / totalSize) * 100;
   const displayValue = getDisplayValue(lang.size, percentages, statsFormat);
 
   const staggerDelay = (index + 3) * 150;
   const color = resolveLangColor(lang);
 
-  return `
-    <g class="stagger" style="animation-delay: ${staggerDelay}ms">
-      <circle cx="5" cy="6" r="5" fill="${color}" />
-      <text data-testid="lang-name" x="15" y="10" class='lang-name'>
-        ${encodeHTML(lang.name)} ${hideProgress || hideValues ? '' : encodeHTML(displayValue)}
-      </text>
-    </g>
-  `;
+  const label = hideProgress || hideValues ? lang.name : `${lang.name} ${displayValue}`;
+
+  return el(
+    'g',
+    { class: 'stagger', style: `animation-delay: ${staggerDelay}ms` },
+    el('circle', { cx: 5, cy: 6, r: 5, fill: color }),
+    el('text', { 'data-testid': 'lang-name', x: 15, y: 10, class: 'lang-name' }, label),
+  );
 };
 
 /**
  * Create compact languages text items for all programming languages.
  *
- * @param props Function properties.
- * @param props.langs Array of programming languages.
- * @param props.totalSize Total size of all languages.
- * @param props.hideProgress Whether to hide percentage.
- * @param props.hideValues Whether to hide stats values.
- * @param props.statsFormat Stats format
  * @returns Programming languages SVG node.
  */
 const createLanguageTextNode = ({
@@ -374,7 +325,7 @@ const createLanguageTextNode = ({
   hideProgress?: boolean | undefined;
   hideValues?: boolean | undefined;
   statsFormat?: string | undefined;
-}): string => {
+}): Array<Child> => {
   const longestLang = getLongestLang(langs);
   const chunked = chunkArray(langs, langs.length / 2);
   const layouts = chunked.map((array) => {
@@ -388,30 +339,18 @@ const createLanguageTextNode = ({
         index,
       }),
     );
-    return flexLayout({
-      items,
-      gap: 25,
-      direction: 'column',
-    }).join('');
+    return flexLayout({ items, gap: 25, direction: 'column' });
   });
 
   const percent = ((longestLang.size / totalSize) * 100).toFixed(2);
   const minGap = 150;
   const maxGap = 20 + measureText(`${longestLang.name} ${percent}%`, 11);
-  return flexLayout({
-    items: layouts,
-    gap: maxGap < minGap ? minGap : maxGap,
-  }).join('');
+  return flexLayout({ items: layouts, gap: maxGap < minGap ? minGap : maxGap });
 };
 
 /**
  * Create donut languages text items for all programming languages.
  *
- * @param props Function properties.
- * @param props.langs Array of programming languages.
- * @param props.totalSize Total size of all languages.
- * @param props.hideValues Whether to hide stats values.
- * @param props.statsFormat Stats format
  * @returns Donut layout programming language SVG node.
  */
 const createDonutLanguagesNode = ({
@@ -424,31 +363,25 @@ const createDonutLanguagesNode = ({
   totalSize: number;
   hideValues?: boolean | undefined;
   statsFormat?: string | undefined;
-}): string => {
-  return flexLayout({
-    items: langs.map((lang, index) => {
-      return createCompactLangNode({
+}): Array<Child> =>
+  flexLayout({
+    items: langs.map((lang, index) =>
+      createCompactLangNode({
         lang,
         totalSize,
         hideProgress: false,
         hideValues,
         statsFormat,
         index,
-      });
-    }),
+      }),
+    ),
     gap: 32,
     direction: 'column',
-  }).join('');
-};
+  });
 
 /**
  * Renders the default language card layout.
  *
- * @param langs Array of programming languages.
- * @param width Card width.
- * @param totalLanguageSize Total size of all languages.
- * @param statsFormat Stats format.
- * @param hideValues Whether to hide stats values.
  * @returns Normal layout card SVG object.
  */
 const renderNormalLayout = (
@@ -457,10 +390,10 @@ const renderNormalLayout = (
   totalLanguageSize: number,
   statsFormat: string,
   hideValues?: boolean,
-): string => {
-  return flexLayout({
-    items: langs.map((lang, index) => {
-      return createProgressTextNode({
+): Array<Child> =>
+  flexLayout({
+    items: langs.map((lang, index) =>
+      createProgressTextNode({
         width,
         name: lang.name,
         color: lang.color || DEFAULT_LANG_COLOR,
@@ -469,22 +402,15 @@ const renderNormalLayout = (
         statsFormat,
         hideValues,
         index,
-      });
-    }),
+      }),
+    ),
     gap: 40,
     direction: 'column',
-  }).join('');
-};
+  });
 
 /**
  * Renders the compact language card layout.
  *
- * @param langs Array of programming languages.
- * @param width Card width.
- * @param totalLanguageSize Total size of all languages.
- * @param hideProgress Whether to hide progress bar.
- * @param statsFormat Stats format.
- * @param hideValues Whether to hide stats values.
  * @returns Compact layout card SVG object.
  */
 const renderCompactLayout = (
@@ -494,66 +420,56 @@ const renderCompactLayout = (
   hideProgress?: boolean,
   statsFormat = 'percentages',
   hideValues?: boolean,
-): string => {
+): Array<Child> => {
   const paddingRight = 50;
   const offsetWidth = width - paddingRight;
   // progressOffset holds the previous language's width and used to offset the next language
   // so that we can stack them one after another, like this: [--][----][---]
   let progressOffset = 0;
-  const compactProgressBar = langs
-    .map((lang) => {
-      const langColor = resolveLangColor(lang);
-
-      const percentage = parseFloat(((lang.size / totalLanguageSize) * offsetWidth).toFixed(2));
-
-      const progress = percentage < 10 ? percentage + 10 : percentage;
-
-      const output = `
-        <rect
-          mask="url(#rect-mask)"
-          data-testid="lang-progress"
-          x="${progressOffset}"
-          y="0"
-          width="${progress}"
-          height="8"
-          fill="${langColor}"
-        />
-      `;
-      progressOffset += percentage;
-      return output;
-    })
-    .join('');
-
-  return `
-  ${
-    hideProgress
-      ? ''
-      : `
-      <mask id="rect-mask">
-          <rect x="0" y="0" width="${offsetWidth}" height="8" fill="white" rx="5"/>
-        </mask>
-        ${compactProgressBar}
-      `
-  }
-    <g transform="translate(0, ${hideProgress ? '0' : '25'})">
-      ${createLanguageTextNode({
+  const compactProgressBar = langs.map((lang) => {
+    const percentage = Number.parseFloat(
+      ((lang.size / totalLanguageSize) * offsetWidth).toFixed(2),
+    );
+    const x = progressOffset;
+    progressOffset += percentage;
+
+    return el('rect', {
+      mask: 'url(#rect-mask)',
+      'data-testid': 'lang-progress',
+      x,
+      y: 0,
+      width: percentage < 10 ? percentage + 10 : percentage,
+      height: 8,
+      fill: resolveLangColor(lang),
+    });
+  });
+
+  return [
+    !hideProgress && [
+      el(
+        'mask',
+        { id: 'rect-mask' },
+        el('rect', { x: 0, y: 0, width: offsetWidth, height: 8, fill: 'white', rx: 5 }),
+      ),
+      compactProgressBar,
+    ],
+    el(
+      'g',
+      { transform: `translate(0, ${hideProgress ? 0 : 25})` },
+      createLanguageTextNode({
         langs,
         totalSize: totalLanguageSize,
         hideProgress,
         statsFormat,
         hideValues,
-      })}
-    </g>
-  `;
+      }),
+    ),
+  ];
 };
 
 /**
  * Renders donut vertical layout to display user's most frequently used programming languages.
  *
- * @param langs Array of programming languages.
- * @param totalLanguageSize Total size of all languages.
- * @param statsFormat Stats format.
- * @param hideValues Whether to hide stats values.
  * @returns Compact layout card SVG object.
  */
 const renderDonutVerticalLayout = (
@@ -561,7 +477,7 @@ const renderDonutVerticalLayout = (
   totalLanguageSize: number,
   statsFormat: string,
   hideValues?: boolean,
-): string => {
+): MarkupElement => {
   // Donut vertical chart radius and total length
   const radius = 80;
   const totalCircleLength = getCircleLength(radius);
@@ -583,22 +499,24 @@ const renderDonutVerticalLayout = (
     const circleLength = totalCircleLength * (percentage / 100);
     const delay = startDelayCoefficient * 100;
 
-    circles.push(`
-      <g class="stagger" style="animation-delay: ${delay}ms">
-        <circle
-          cx="150"
-          cy="100"
-          r="${radius}"
-          fill="transparent"
-          stroke="${langColor}"
-          stroke-width="25"
-          stroke-dasharray="${totalCircleLength}"
-          stroke-dashoffset="${indent}"
-          size="${percentage}"
-          data-testid="lang-donut"
-        />
-      </g>
-    `);
+    circles.push(
+      el(
+        'g',
+        { class: 'stagger', style: `animation-delay: ${delay}ms` },
+        el('circle', {
+          cx: 150,
+          cy: 100,
+          r: radius,
+          fill: 'transparent',
+          stroke: langColor,
+          'stroke-width': 25,
+          'stroke-dasharray': totalCircleLength,
+          'stroke-dashoffset': indent,
+          size: percentage,
+          'data-testid': 'lang-donut',
+        }),
+      ),
+    );
 
     // Update the indent for the next part
     indent += circleLength;
@@ -606,35 +524,31 @@ const renderDonutVerticalLayout = (
     startDelayCoefficient += 1;
   }
 
-  return `
-    <svg data-testid="lang-items">
-      <g transform="translate(0, 0)">
-        <svg data-testid="donut">
-          ${circles.join('')}
-        </svg>
-      </g>
-      <g transform="translate(0, 220)">
-        <svg data-testid="lang-names" x="${CARD_PADDING}">
-          ${createLanguageTextNode({
-            langs,
-            totalSize: totalLanguageSize,
-            hideProgress: false,
-            statsFormat,
-            hideValues,
-          })}
-        </svg>
-      </g>
-    </svg>
-  `;
+  return el(
+    'svg',
+    { 'data-testid': 'lang-items' },
+    el('svg', { 'data-testid': 'donut' }, circles),
+    el(
+      'g',
+      { transform: 'translate(0, 220)' },
+      el(
+        'svg',
+        { 'data-testid': 'lang-names', x: CARD_PADDING },
+        createLanguageTextNode({
+          langs,
+          totalSize: totalLanguageSize,
+          hideProgress: false,
+          statsFormat,
+          hideValues,
+        }),
+      ),
+    ),
+  );
 };
 
 /**
  * Renders pie layout to display user's most frequently used programming languages.
  *
- * @param langs Array of programming languages.
- * @param totalLanguageSize Total size of all languages.
- * @param statsFormat Stats format.
- * @param hideValues Whether to hide stats values.
  * @returns Compact layout card SVG object.
  */
 const renderPieLayout = (
@@ -642,7 +556,7 @@ const renderPieLayout = (
   totalLanguageSize: number,
   statsFormat: string,
   hideValues?: boolean,
-): string => {
+): MarkupElement => {
   // Pie chart radius and center coordinates
   const radius = 90;
   const centerX = 150;
@@ -662,17 +576,17 @@ const renderPieLayout = (
     const langColor = resolveLangColor(lang);
 
     if (langs.length === 1) {
-      paths.push(`
-        <circle
-          cx="${centerX}"
-          cy="${centerY}"
-          r="${radius}"
-          stroke="none"
-          fill="${langColor}"
-          data-testid="lang-pie"
-          size="100"
-        />
-      `);
+      paths.push(
+        el('circle', {
+          cx: centerX,
+          cy: centerY,
+          r: radius,
+          stroke: 'none',
+          fill: langColor,
+          'data-testid': 'lang-pie',
+          size: 100,
+        }),
+      );
       break;
     }
 
@@ -695,16 +609,18 @@ const renderPieLayout = (
     const delay = startDelayCoefficient * 100;
 
     // SVG arc markup
-    paths.push(`
-      <g class="stagger" style="animation-delay: ${delay}ms">
-        <path
-          data-testid="lang-pie"
-          size="${percentage}"
-          d="M ${centerX} ${centerY} L ${startPoint.x} ${startPoint.y} A ${radius} ${radius} 0 ${largeArcFlag} 1 ${endPoint.x} ${endPoint.y} Z"
-          fill="${langColor}"
-        />
-      </g>
-    `);
+    paths.push(
+      el(
+        'g',
+        { class: 'stagger', style: `animation-delay: ${delay}ms` },
+        el('path', {
+          'data-testid': 'lang-pie',
+          size: percentage,
+          d: `M ${centerX} ${centerY} L ${startPoint.x} ${startPoint.y} A ${radius} ${radius} 0 ${largeArcFlag} 1 ${endPoint.x} ${endPoint.y} Z`,
+          fill: langColor,
+        }),
+      ),
+    );
 
     // Update the start angle for the next part
     startAngle = endAngle;
@@ -712,35 +628,31 @@ const renderPieLayout = (
     startDelayCoefficient += 1;
   }
 
-  return `
-    <svg data-testid="lang-items">
-      <g transform="translate(0, 0)">
-        <svg data-testid="pie">
-          ${paths.join('')}
-        </svg>
-      </g>
-      <g transform="translate(0, 220)">
-        <svg data-testid="lang-names" x="${CARD_PADDING}">
-          ${createLanguageTextNode({
-            langs,
-            totalSize: totalLanguageSize,
-            hideProgress: false,
-            statsFormat,
-            hideValues,
-          })}
-        </svg>
-      </g>
-    </svg>
-  `;
+  return el(
+    'svg',
+    { 'data-testid': 'lang-items' },
+    el('svg', { 'data-testid': 'pie' }, paths),
+    el(
+      'g',
+      { transform: 'translate(0, 220)' },
+      el(
+        'svg',
+        { 'data-testid': 'lang-names', x: CARD_PADDING },
+        createLanguageTextNode({
+          langs,
+          totalSize: totalLanguageSize,
+          hideProgress: false,
+          statsFormat,
+          hideValues,
+        }),
+      ),
+    ),
+  );
 };
 
 /**
  * Creates the SVG paths for the language donut chart.
  *
- * @param cx Donut center x-position.
- * @param cy Donut center y-position.
- * @param radius Donut arc Radius.
- * @param percentages Array with donut section percentages.
  * @returns Array of svg path elements
  */
 const createDonutPaths = (
@@ -754,7 +666,7 @@ const createDonutPaths = (
 
   const totalPercent = percentages.reduce((acc, curr) => acc + curr, 0);
   for (const rawPercent of percentages) {
-    const percent = parseFloat(((rawPercent / totalPercent) * 100).toFixed(2));
+    const percent = Number.parseFloat(((rawPercent / totalPercent) * 100).toFixed(2));
 
     const endAngle = 3.6 * percent + startAngle;
     const startPoint = polarToCartesian(cx, cy, radius, endAngle - 90); // rotate donut 90 degrees counter-clockwise.
@@ -774,11 +686,6 @@ const createDonutPaths = (
 /**
  * Renders the donut language card layout.
  *
- * @param langs Array of programming languages.
- * @param width Card width.
- * @param totalLanguageSize Total size of all languages.
- * @param statsFormat Stats format.
- * @param hideValues Whether to hide stats values.
  * @returns Donut layout card SVG object.
  */
 const renderDonutLayout = (
@@ -787,9 +694,9 @@ const renderDonutLayout = (
   totalLanguageSize: number,
   statsFormat: string,
   hideValues?: boolean,
-): string => {
+): Array<Child> => {
   if (!Number.isFinite(width)) {
-    throw new Error(`Invalid width: "${width}"`);
+    throw new TypeError(`Invalid width: "${width}"`);
   }
 
   const centerX = width / 3;
@@ -797,59 +704,55 @@ const renderDonutLayout = (
   const radius = centerX - 60;
   const strokeWidth = 12;
 
-  const colors = langs.map(resolveLangColor);
+  const colors = langs.map((lang) => resolveLangColor(lang));
   const langsPercents = langs.map((lang) =>
-    parseFloat(((lang.size / totalLanguageSize) * 100).toFixed(2)),
+    Number.parseFloat(((lang.size / totalLanguageSize) * 100).toFixed(2)),
   );
 
   const langPaths = createDonutPaths(centerX, centerY, radius, langsPercents);
 
-  const donutPaths =
+  const donutPaths: Array<Child> =
     langs.length === 1
-      ? `<circle cx="${centerX}" cy="${centerY}" r="${radius}" stroke="${colors[0] ?? DEFAULT_LANG_COLOR}" fill="none" stroke-width="${strokeWidth}" data-testid="lang-donut" size="100"/>`
-      : langPaths
-          .map((section, index) => {
-            const staggerDelay = (index + 3) * 100;
-            const delay = staggerDelay + 300;
-
-            const output = `
-       <g class="stagger" style="animation-delay: ${delay}ms">
-        <path
-          data-testid="lang-donut"
-          size="${section.percent}"
-          d="${section.d}"
-          stroke="${colors[index] ?? DEFAULT_LANG_COLOR}"
-          fill="none"
-          stroke-width="${strokeWidth}">
-        </path>
-      </g>
-      `;
-
-            return output;
-          })
-          .join('');
-
-  const donut = `<svg width="${width}" height="${width}">${donutPaths}</svg>`;
-
-  return `
-    <g transform="translate(0, 0)">
-      <g transform="translate(0, 0)">
-        ${createDonutLanguagesNode({ langs, totalSize: totalLanguageSize, hideValues, statsFormat })}
-      </g>
-
-      <g transform="translate(125, ${donutCenterTranslation(langs.length)})">
-        ${donut}
-      </g>
-    </g>
-  `;
+      ? [
+          el('circle', {
+            cx: centerX,
+            cy: centerY,
+            r: radius,
+            stroke: colors[0] ?? DEFAULT_LANG_COLOR,
+            fill: 'none',
+            'stroke-width': strokeWidth,
+            'data-testid': 'lang-donut',
+            size: 100,
+          }),
+        ]
+      : langPaths.map((section, index) =>
+          el(
+            'g',
+            { class: 'stagger', style: `animation-delay: ${(index + 3) * 100 + 300}ms` },
+            el('path', {
+              'data-testid': 'lang-donut',
+              size: section.percent,
+              d: section.d,
+              stroke: colors[index] ?? DEFAULT_LANG_COLOR,
+              fill: 'none',
+              'stroke-width': strokeWidth,
+            }),
+          ),
+        );
+
+  return [
+    createDonutLanguagesNode({ langs, totalSize: totalLanguageSize, hideValues, statsFormat }),
+    el(
+      'g',
+      { transform: `translate(125, ${donutCenterTranslation(langs.length)})` },
+      el('svg', { width, height: width }, donutPaths),
+    ),
+  ];
 };
 
 /**
  * Creates the no languages data SVG node.
  *
- * @param props Object with function properties.
- * @param props.text No languages data translated text.
- * @param props.layout Card layout.
  * @returns No languages data SVG node string.
  */
 const noLanguagesDataNode = ({
@@ -858,20 +761,20 @@ const noLanguagesDataNode = ({
 }: {
   text: string;
   layout: TopLangLayout | undefined;
-}): string => {
-  return `
-    <text x="${
-      layout === 'pie' || layout === 'donut-vertical' ? CARD_PADDING : 0
-    }" y="11" class="stat bold">${encodeHTML(text)}</text>
-  `;
-};
+}): MarkupElement =>
+  el(
+    'text',
+    {
+      x: layout === 'pie' || layout === 'donut-vertical' ? CARD_PADDING : 0,
+      y: 11,
+      class: 'stat bold',
+    },
+    text,
+  );
 
 /**
  * Get default languages count for provided card layout.
  *
- * @param props Function properties.
- * @param props.layout Input layout string.
- * @param props.hide_progress Input hide_progress parameter value.
  * @returns Default languages count for input layout.
  */
 const getDefaultLanguagesCountByLayout = ({
@@ -883,28 +786,25 @@ const getDefaultLanguagesCountByLayout = ({
 }): number => {
   if (layout === 'compact' || hide_progress === true) {
     return COMPACT_LAYOUT_DEFAULT_LANGS_COUNT;
-  } else if (layout === 'donut') {
+  }
+  if (layout === 'donut') {
     return DONUT_LAYOUT_DEFAULT_LANGS_COUNT;
-  } else if (layout === 'donut-vertical') {
+  }
+  if (layout === 'donut-vertical') {
     return DONUT_VERTICAL_LAYOUT_DEFAULT_LANGS_COUNT;
-  } else if (layout === 'pie') {
+  }
+  if (layout === 'pie') {
     return PIE_LAYOUT_DEFAULT_LANGS_COUNT;
-  } else {
-    return NORMAL_LAYOUT_DEFAULT_LANGS_COUNT;
   }
+  return NORMAL_LAYOUT_DEFAULT_LANGS_COUNT;
 };
 
 /**
  * Renders card that display user's most frequently used programming languages.
  *
- * @param topLangs User's most frequently used programming languages.
- * @param options Card options.
  * @returns Language card SVG object.
  */
-const renderTopLanguages = (
-  topLangs: TopLangData,
-  options: CardOptions<TopLangOptions> = {},
-): string => {
+const renderCard = (topLangs: TopLangData, options: CardOptions<TopLangOptions> = {}): string => {
   const {
     hide_title = false,
     hide_border = false,
@@ -929,7 +829,7 @@ const renderTopLanguages = (
   const { langs, totalLanguageSize } = trimTopLanguages(topLangs, langs_count, hide);
 
   let width = card_width
-    ? isNaN(card_width)
+    ? Number.isNaN(card_width)
       ? DEFAULT_CARD_WIDTH
       : card_width < MIN_CARD_WIDTH
         ? MIN_CARD_WIDTH
@@ -939,7 +839,7 @@ const renderTopLanguages = (
 
   const { lightColors, darkColors } = getLightDarkColors(options);
 
-  let finalLayout: string;
+  let finalLayout: Child;
   if (langs.length === 0) {
     height = COMPACT_LAYOUT_BASE_HEIGHT;
     finalLayout = noLanguagesDataNode({
@@ -965,7 +865,9 @@ const renderTopLanguages = (
     );
   } else if (layout === 'donut') {
     height = calculateDonutLayoutHeight(langs.length);
-    width = width + 50; // padding
+    // A donut defaults a step wider so the chart has its room; a width asked for
+    // explicitly keeps the extra it has always been given instead of being snapped.
+    width = width === DEFAULT_CARD_WIDTH ? CARD_WIDTH.standard : width + DONUT_EXTRA_WIDTH;
     finalLayout = renderDonutLayout(langs, width, totalLanguageSize, stats_format, hide_values);
   } else {
     finalLayout = renderNormalLayout(langs, width, totalLanguageSize, stats_format, hide_values);
@@ -974,6 +876,7 @@ const renderTopLanguages = (
   const card = new Card({
     customTitle: custom_title,
     defaultTitle: i18n.t('langcard.title'),
+    titlePrefixIcon: CARD_ICON.topLanguages,
     width,
     height,
     border_radius,
@@ -987,52 +890,36 @@ const renderTopLanguages = (
   card.setHideBorder(hide_border);
   card.setHideTitle(hide_title);
   card.setCSS({
-    light: ({ textColor, progBarBgColor }) => `
-    @keyframes slideInAnimation {
-      from {
-        width: 0;
-      }
-      to {
-        width: calc(100%-100px);
-      }
-    }
-    @keyframes growWidthAnimation {
-      from {
-        width: 0;
-      }
-      to {
-        width: 100%;
-      }
-    }
-    .stat {
-      font: 600 14px 'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif; fill: ${textColor};
-    }
-    @supports(-moz-appearance: auto) {
-      /* Selector detects Firefox */
-      .stat { font-size:12px; }
-    }
-    .bold { font-weight: 700 }
-    .lang-name {
-      font: 400 11px "Segoe UI", Ubuntu, Sans-Serif;
-      fill: ${textColor};
-    }
-    .stagger {
-      opacity: 0;
-      animation: fadeInAnimation 0.3s ease-in-out forwards;
-    }
-    #rect-mask rect{
-      animation: slideInAnimation 1s ease-in-out forwards;
-    }
-    .lang-progress{
-      animation: growWidthAnimation 0.6s ease-in-out forwards;
-    }
-    .progress-background { fill: ${progBarBgColor}; }
-    `,
-    dark: ({ textColor, progBarBgColor }) => `
-      .stat { fill: ${textColor}; }
-      .lang-name { fill: ${textColor}; }
-      .progress-background { fill: ${progBarBgColor}; }
-    `,
+    light: ({ textColor, progBarBgColor }) => [
+      atRule(
+        '@keyframes slideInAnimation',
+        rule('from', { width: 0 }),
+        // Invalid on purpose — `calc` needs spaces around its `-`. Browsers drop the
+        // declaration and animate to the rect's own width, which is the reveal the mask wants.
+        rule('to', { width: 'calc(100%-100px)' }),
+      ),
+      atRule(
+        '@keyframes growWidthAnimation',
+        rule('from', { width: 0 }),
+        rule('to', { width: '100%' }),
+      ),
+      rule('.stat', {
+        font: font('regular', 'body'),
+        fill: textColor,
+      }),
+      firefoxFontSize(['.stat'], 'small'),
+      rule('.bold', { 'font-weight': FONT_WEIGHT.semibold }),
+      rule('.lang-name', { font: font('regular', 'micro'), fill: textColor }),
+      rule('.stagger', { opacity: 0, animation: 'fadeInAnimation 0.3s ease-in-out forwards' }),
+      rule('#rect-mask rect', { animation: 'slideInAnimation 1s ease-in-out forwards' }),
+      rule('.lang-progress', { animation: 'growWidthAnimation 0.6s ease-in-out forwards' }),
+      rule('.progress-background', { fill: progBarBgColor }),
+    ],
+    dark: ({ textColor, progBarBgColor }) => [
+      rule('.stat', { fill: textColor }),
+      rule('.lang-name', { fill: textColor }),
+      rule('.progress-background', { fill: progBarBgColor }),
+    ],
   });
 
   // `role="img"` hides the inner text from assistive tech, so everything the card
@@ -1048,13 +935,21 @@ const renderTopLanguages = (
     return card.render(finalLayout);
   }
 
-  return card.render(`
-    <svg data-testid="lang-items" x="${CARD_PADDING}">
-      ${finalLayout}
-    </svg>
-  `);
+  return card.render(el('svg', { 'data-testid': 'lang-items', x: CARD_PADDING }, finalLayout));
 };
 
+/**
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * They ride on the renderer so a list cannot be found without what draws it;
+ * the api handler forwards them onto its own export, which is what a UI reads.
+ */
+const renderTopLanguages = Object.assign(renderCard, {
+  OPTIONS: {
+    layout: TOP_LANG_LAYOUTS,
+    stats_format: TOP_LANG_STATS_FORMATS,
+  },
+});
+
 export {
   getLongestLang,
   degreesToRadians,
@@ -1069,9 +964,7 @@ export {
   calculatePieLayoutHeight,
   donutCenterTranslation,
   trimTopLanguages,
-  renderTopLanguages,
   MIN_CARD_WIDTH,
   getDefaultLanguagesCountByLayout,
-  TOP_LANG_LAYOUTS,
-  TOP_LANG_STATS_FORMATS,
+  renderTopLanguages,
 };