feat: add bytes stats format option for top-languages card (#3708)

* feat: add `display_bytes` option to top-languages.

* docs: add description about display bytes in top-languages

* feat: add `stats_format` option instead of `display_bytes`

* docs: add description about stats format in top-languages

* refactor: rewrite with function to determine display value

* docs: add `stats_format`to table of parameter

* fix: remove unnecessary decimal part from format of bytes

* tests: add tests of stats_format in top-langs card

* Update tests/renderTopLanguagesCard.test.js

Co-authored-by: Copilot <[email protected]>

* Update readme.md

Co-authored-by: Copilot <[email protected]>

* prettier

* jsdoc

---------

Co-authored-by: Alexandr <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

api/top-langs.js

@@ -34,6 +34,7 @@ export default async (req, res) => {
     border_color,
     disable_animations,
     hide_progress,
+    stats_format,
   } = req.query;
   res.setHeader("Content-Type", "image/svg+xml");
 
@@ -85,6 +86,16 @@ export default async (req, res) => {
     );
   }
 
+  if (
+    stats_format !== undefined &&
+    (typeof stats_format !== "string" ||
+      !["bytes", "percentages"].includes(stats_format))
+  ) {
+    return res.send(
+      renderError("Something went wrong", "Incorrect stats_format input"),
+    );
+  }
+
   try {
     const topLangs = await fetchTopLanguages(
       username,
@@ -125,6 +136,7 @@ export default async (req, res) => {
         locale: locale ? locale.toLowerCase() : null,
         disable_animations: parseBoolean(disable_animations),
         hide_progress: parseBoolean(hide_progress),
+        stats_format,
       }),
     );
   } catch (err) {

readme.md

@@ -74,6 +74,7 @@
     - [Donut Vertical Chart Language Card Layout](#donut-vertical-chart-language-card-layout)
     - [Pie Chart Language Card Layout](#pie-chart-language-card-layout)
     - [Hide Progress Bars](#hide-progress-bars)
+    - [Change format of language's stats](#change-format-of-languages-stats)
     - [Demo](#demo-2)
 - [WakaTime Stats Card](#wakatime-stats-card)
     - [Options](#options-3)
@@ -468,6 +469,7 @@ You can customize the appearance and behavior of the top languages card using th
 | `hide_progress` | Uses the compact layout option, hides percentages, and removes the bars. | boolean | `false` |
 | `size_weight` | Configures language stats algorithm (see [Language stats algorithm](#language-stats-algorithm)). | integer | `1` |
 | `count_weight` | Configures language stats algorithm (see [Language stats algorithm](#language-stats-algorithm)). | integer | `0` |
+| `stats_format` | Switches between two available formats for language's stats `percentages` and `bytes`. | enum | `percentages` |
 
 > [!WARNING]\
 > Language names should be URI-escaped, as specified in [Percent Encoding](https://en.wikipedia.org/wiki/Percent-encoding)
@@ -556,6 +558,15 @@ You can use the `&hide_progress=true` option to hide the percentages and the pro
 ![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&hide_progress=true)
 ```
 
+### Change format of language's stats
+
+You can use the `&stats_format=bytes` option to display the stats in bytes instead of percentage.
+
+```md
+![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&stats_format=bytes)
+```
+
+
 ### Demo
 
 ![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra)
@@ -580,6 +591,11 @@ You can use the `&hide_progress=true` option to hide the percentages and the pro
 
 ![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra\&hide_progress=true)
 
+
+*  Display bytes instead of percentage
+
+![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra\&stats_format=bytes)
+
 # WakaTime Stats Card
 
 > [!WARNING]\

src/cards/top-languages.js

@@ -9,6 +9,7 @@ import {
   getCardColors,
   lowercaseTrim,
   measureText,
+  formatBytes,
 } from "../common/utils.js";
 import { langCardLocales } from "../translations.js";
 
@@ -196,27 +197,52 @@ const trimTopLanguages = (topLangs, langs_count, hide) => {
   return { langs, totalLanguageSize };
 };
 
+/**
+ * Get display value corresponding to the format.
+ *
+ * @param {number} size Bytes size.
+ * @param {number} percentages Percentage value.
+ * @param {string} format Format of the stats.
+ * @returns {string} Display value.
+ */
+const getDisplayValue = (size, percentages, format) => {
+  return format === "bytes" ? formatBytes(size) : `${percentages.toFixed(2)}%`;
+};
+
 /**
  * Create progress bar text item for a programming language.
  *
  * @param {object} props Function properties.
  * @param {number} props.width The card width
  * @param {string} props.color Color of the programming language.
  * @param {string} props.name Name of the programming language.
- * @param {number} props.progress Usage of the programming language in percentage.
+ * @param {number} props.size Size of the programming language.
+ * @param {number} props.totalSize Total size of all languages.
+ * @param {string} props.statsFormat Stats format.
  * @param {number} props.index Index of the programming language.
  * @returns {string} Programming language SVG node.
  */
-const createProgressTextNode = ({ width, color, name, progress, index }) => {
+const createProgressTextNode = ({
+  width,
+  color,
+  name,
+  size,
+  totalSize,
+  statsFormat,
+  index,
+}) => {
   const staggerDelay = (index + 3) * 150;
   const paddingRight = 95;
   const progressTextX = width - paddingRight + 10;
   const progressWidth = width - paddingRight;
 
+  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">${name}</text>
-      <text x="${progressTextX}" y="34" class="lang-name">${progress}%</text>
+      <text x="${progressTextX}" y="34" class="lang-name">${displayValue}</text>
       ${createProgressNode({
         x: 0,
         y: 25,
@@ -237,19 +263,28 @@ const createProgressTextNode = ({ width, color, name, progress, index }) => {
  * @param {Lang} props.lang Programming language object.
  * @param {number} props.totalSize Total size of all languages.
  * @param {boolean=} props.hideProgress Whether to hide percentage.
+ * @param {string=} props.statsFormat Stats format
  * @param {number} props.index Index of the programming language.
  * @returns {string} Compact layout programming language SVG node.
  */
-const createCompactLangNode = ({ lang, totalSize, hideProgress, index }) => {
-  const percentage = ((lang.size / totalSize) * 100).toFixed(2);
+const createCompactLangNode = ({
+  lang,
+  totalSize,
+  hideProgress,
+  statsFormat = "percentages",
+  index,
+}) => {
+  const percentages = (lang.size / totalSize) * 100;
+  const displayValue = getDisplayValue(lang.size, percentages, statsFormat);
+
   const staggerDelay = (index + 3) * 150;
   const color = lang.color || "#858585";
 
   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'>
-        ${lang.name} ${hideProgress ? "" : percentage + "%"}
+        ${lang.name} ${hideProgress ? "" : displayValue}
       </text>
     </g>
   `;
@@ -262,9 +297,15 @@ const createCompactLangNode = ({ lang, totalSize, hideProgress, index }) => {
  * @param {Lang[]} props.langs Array of programming languages.
  * @param {number} props.totalSize Total size of all languages.
  * @param {boolean=} props.hideProgress Whether to hide percentage.
+ * @param {string=} props.statsFormat Stats format
  * @returns {string} Programming languages SVG node.
  */
-const createLanguageTextNode = ({ langs, totalSize, hideProgress }) => {
+const createLanguageTextNode = ({
+  langs,
+  totalSize,
+  hideProgress,
+  statsFormat,
+}) => {
   const longestLang = getLongestLang(langs);
   const chunked = chunkArray(langs, langs.length / 2);
   const layouts = chunked.map((array) => {
@@ -274,6 +315,7 @@ const createLanguageTextNode = ({ langs, totalSize, hideProgress }) => {
         lang,
         totalSize,
         hideProgress,
+        statsFormat,
         index,
       }),
     );
@@ -299,15 +341,17 @@ const createLanguageTextNode = ({ langs, totalSize, hideProgress }) => {
  * @param {object} props Function properties.
  * @param {Lang[]} props.langs Array of programming languages.
  * @param {number} props.totalSize Total size of all languages.
+ * @param {string} props.statsFormat Stats format
  * @returns {string} Donut layout programming language SVG node.
  */
-const createDonutLanguagesNode = ({ langs, totalSize }) => {
+const createDonutLanguagesNode = ({ langs, totalSize, statsFormat }) => {
   return flexLayout({
     items: langs.map((lang, index) => {
       return createCompactLangNode({
         lang,
         totalSize,
         hideProgress: false,
+        statsFormat,
         index,
       });
     }),
@@ -322,18 +366,19 @@ const createDonutLanguagesNode = ({ langs, totalSize }) => {
  * @param {Lang[]} langs Array of programming languages.
  * @param {number} width Card width.
  * @param {number} totalLanguageSize Total size of all languages.
+ * @param {string} statsFormat Stats format.
  * @returns {string} Normal layout card SVG object.
  */
-const renderNormalLayout = (langs, width, totalLanguageSize) => {
+const renderNormalLayout = (langs, width, totalLanguageSize, statsFormat) => {
   return flexLayout({
     items: langs.map((lang, index) => {
       return createProgressTextNode({
         width,
         name: lang.name,
         color: lang.color || DEFAULT_LANG_COLOR,
-        progress: parseFloat(
-          ((lang.size / totalLanguageSize) * 100).toFixed(2),
-        ),
+        size: lang.size,
+        totalSize: totalLanguageSize,
+        statsFormat,
         index,
       });
     }),
@@ -349,9 +394,16 @@ const renderNormalLayout = (langs, width, totalLanguageSize) => {
  * @param {number} width Card width.
  * @param {number} totalLanguageSize Total size of all languages.
  * @param {boolean=} hideProgress Whether to hide progress bar.
+ * @param {string} statsFormat Stats format.
  * @returns {string} Compact layout card SVG object.
  */
-const renderCompactLayout = (langs, width, totalLanguageSize, hideProgress) => {
+const renderCompactLayout = (
+  langs,
+  width,
+  totalLanguageSize,
+  hideProgress,
+  statsFormat = "percentages",
+) => {
   const paddingRight = 50;
   const offsetWidth = width - paddingRight;
   // progressOffset holds the previous language's width and used to offset the next language
@@ -397,6 +449,7 @@ const renderCompactLayout = (langs, width, totalLanguageSize, hideProgress) => {
         langs,
         totalSize: totalLanguageSize,
         hideProgress,
+        statsFormat,
       })}
     </g>
   `;
@@ -407,9 +460,10 @@ const renderCompactLayout = (langs, width, totalLanguageSize, hideProgress) => {
  *
  * @param {Lang[]} langs Array of programming languages.
  * @param {number} totalLanguageSize Total size of all languages.
+ * @param {string} statsFormat Stats format.
  * @returns {string} Compact layout card SVG object.
  */
-const renderDonutVerticalLayout = (langs, totalLanguageSize) => {
+const renderDonutVerticalLayout = (langs, totalLanguageSize, statsFormat) => {
   // Donut vertical chart radius and total length
   const radius = 80;
   const totalCircleLength = getCircleLength(radius);
@@ -465,6 +519,7 @@ const renderDonutVerticalLayout = (langs, totalLanguageSize) => {
             langs,
             totalSize: totalLanguageSize,
             hideProgress: false,
+            statsFormat,
           })}
         </svg>
       </g>
@@ -477,9 +532,10 @@ const renderDonutVerticalLayout = (langs, totalLanguageSize) => {
  *
  * @param {Lang[]} langs Array of programming languages.
  * @param {number} totalLanguageSize Total size of all languages.
+ * @param {string} statsFormat Stats format.
  * @returns {string} Compact layout card SVG object.
  */
-const renderPieLayout = (langs, totalLanguageSize) => {
+const renderPieLayout = (langs, totalLanguageSize, statsFormat) => {
   // Pie chart radius and center coordinates
   const radius = 90;
   const centerX = 150;
@@ -560,6 +616,7 @@ const renderPieLayout = (langs, totalLanguageSize) => {
             langs,
             totalSize: totalLanguageSize,
             hideProgress: false,
+            statsFormat,
           })}
         </svg>
       </g>
@@ -610,9 +667,10 @@ const createDonutPaths = (cx, cy, radius, percentages) => {
  * @param {Lang[]} langs Array of programming languages.
  * @param {number} width Card width.
  * @param {number} totalLanguageSize Total size of all languages.
+ * @param {string} statsFormat Stats format.
  * @returns {string} Donut layout card SVG object.
  */
-const renderDonutLayout = (langs, width, totalLanguageSize) => {
+const renderDonutLayout = (langs, width, totalLanguageSize, statsFormat) => {
   const centerX = width / 3;
   const centerY = width / 3;
   const radius = centerX - 60;
@@ -655,7 +713,7 @@ const renderDonutLayout = (langs, width, totalLanguageSize) => {
   return `
     <g transform="translate(0, 0)">
       <g transform="translate(0, 0)">
-        ${createDonutLanguagesNode({ langs, totalSize: totalLanguageSize })}
+        ${createDonutLanguagesNode({ langs, totalSize: totalLanguageSize, statsFormat })}
       </g>
 
       <g transform="translate(125, ${donutCenterTranslation(langs.length)})">
@@ -738,6 +796,7 @@ const renderTopLanguages = (topLangs, options = {}) => {
     border_radius,
     border_color,
     disable_animations,
+    stats_format = "percentages",
   } = options;
 
   const i18n = new I18n({
@@ -779,10 +838,14 @@ const renderTopLanguages = (topLangs, options = {}) => {
     });
   } else if (layout === "pie") {
     height = calculatePieLayoutHeight(langs.length);
-    finalLayout = renderPieLayout(langs, totalLanguageSize);
+    finalLayout = renderPieLayout(langs, totalLanguageSize, stats_format);
   } else if (layout === "donut-vertical") {
     height = calculateDonutVerticalLayoutHeight(langs.length);
-    finalLayout = renderDonutVerticalLayout(langs, totalLanguageSize);
+    finalLayout = renderDonutVerticalLayout(
+      langs,
+      totalLanguageSize,
+      stats_format,
+    );
   } else if (layout === "compact" || hide_progress == true) {
     height =
       calculateCompactLayoutHeight(langs.length) + (hide_progress ? -25 : 0);
@@ -792,13 +855,24 @@ const renderTopLanguages = (topLangs, options = {}) => {
       width,
       totalLanguageSize,
       hide_progress,
+      stats_format,
     );
   } else if (layout === "donut") {
     height = calculateDonutLayoutHeight(langs.length);
     width = width + 50; // padding
-    finalLayout = renderDonutLayout(langs, width, totalLanguageSize);
+    finalLayout = renderDonutLayout(
+      langs,
+      width,
+      totalLanguageSize,
+      stats_format,
+    );
   } else {
-    finalLayout = renderNormalLayout(langs, width, totalLanguageSize);
+    finalLayout = renderNormalLayout(
+      langs,
+      width,
+      totalLanguageSize,
+      stats_format,
+    );
   }
 
   const card = new Card({

src/cards/types.d.ts

@@ -44,6 +44,7 @@ export type TopLangOptions = CommonOptions & {
   langs_count: number;
   disable_animations: boolean;
   hide_progress: boolean;
+  stats_format: "percentages" | "bytes";
 };
 
 export type WakaTimeOptions = CommonOptions & {