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

package/src/cards/stats.ts

@@ -1,15 +1,17 @@
-import { Card } from '../common/Card.js';
-import { getLightDarkColors } from '../common/color.js';
-import type { CardColors } from '../common/color.js';
-import { CardError } from '../common/error.js';
-import { I18n } from '../common/I18n.js';
-import { icons, rankIcon } from '../common/icons.js';
-import { buildSearchFilter, clampValue } from '../common/ops.js';
-import { createTextNode, flexLayout, measureText } from '../common/render.js';
-import type { StatsData } from '../fetchers/types.js';
-import { statCardLocales, wakatimeCardLocales } from '../translations.js';
-
-import type { CardOptions, CommonCardOptions } from './options.js';
+import { Card } from '../common/Card.ts';
+import { getLightDarkColors } from '../common/color.ts';
+import type { CardColors } from '../common/color.ts';
+import { CardError } from '../common/error.ts';
+import { I18n } from '../common/I18n.ts';
+import { icons, rankIcon } from '../common/icons.ts';
+import { buildSearchFilter, clampValue } from '../common/ops.ts';
+import { createTextNode, flexLayout, measureText } from '../common/render.ts';
+import type { StatsData } from '../fetchers/types.ts';
+import type { Child, CssChild } from '../markup/index.ts';
+import { atRule, cssComment, el, rule } from '../markup/index.ts';
+import { statCardLocales, wakatimeCardLocales } from '../translations.ts';
+
+import type { CardOptions, CommonCardOptions } from './options.ts';
 
 const CARD_MIN_WIDTH = 287;
 const CARD_DEFAULT_WIDTH = 287;
@@ -18,6 +20,18 @@ const RANK_CARD_DEFAULT_WIDTH = 450;
 const RANK_ONLY_CARD_MIN_WIDTH = 290;
 const RANK_ONLY_CARD_DEFAULT_WIDTH = 290;
 
+const STAT_FONT_SIZE = 14;
+/** Padding the card keeps at its edges; matches `Card`'s own `paddingX`. */
+const CARD_PADDING_X = 25;
+/** How far a stat row is translated into the card; see `createTextNode`. */
+const STAT_ROW_X = 25;
+/** Room the rank ring needs at the right edge, so a value never runs into it. */
+const RANK_GUTTER = 120;
+/** `createTextNode`'s own label offset, which it applies only when icons are shown. */
+const LABEL_X_OFFSET = 25;
+/** Smallest gap kept between the longest label and its value. */
+const LABEL_VALUE_GAP = 16;
+
 /** Rank indicators the card can draw; the api validates `rank_icon` against this. */
 const RANK_ICONS = ['default', 'github', 'percentile'] as const;
 type RankIcon = (typeof RANK_ICONS)[number];
@@ -44,7 +58,7 @@ interface StatCardOptions extends CommonCardOptions {
 
 /** Meta data for a stat, used to build its text node and accessibility label. */
 interface StatItem {
-  icon: string;
+  icon: Child;
   label: string;
   value: number | string;
   id: string;
@@ -53,7 +67,7 @@ interface StatItem {
 }
 
 /** Long locales that need more space for text. Keep sorted alphabetically. */
-const LONG_LOCALES: Array<string> = [
+const LONG_LOCALES: ReadonlySet<string> = new Set([
   'az',
   'bg',
   'cs',
@@ -80,58 +94,37 @@ const LONG_LOCALES: Array<string> = [
   'uk-ua',
   'uz',
   'zh-tw',
-];
+]);
 
 /**
  * Calculates progress along the boundary of the circle, i.e. its circumference.
  *
- * @param value The rank value to calculate progress for.
  * @returns Progress value.
  */
 const calculateCircleProgress = (value: number): number => {
   const radius = 40;
-  const c = Math.PI * (radius * 2);
-
-  if (value < 0) {
-    value = 0;
-  }
-  if (value > 100) {
-    value = 100;
-  }
+  const circumference = Math.PI * (radius * 2);
+  const clamped = Math.min(Math.max(value, 0), 100);
 
-  return ((100 - value) / 100) * c;
+  return ((100 - clamped) / 100) * circumference;
 };
 
 /**
  * Retrieves the animation to display progress along the circumference of circle
  * from the beginning to the given value in a clockwise direction.
  *
- * @param props The props object.
- * @param props.progress The progress value to animate to.
  * @returns Progress animation css.
  */
-const getProgressAnimation = ({ progress }: { progress: number }): string => {
-  return `
-    @keyframes rankAnimation {
-      from {
-        stroke-dashoffset: ${calculateCircleProgress(0)};
-      }
-      to {
-        stroke-dashoffset: ${calculateCircleProgress(progress)};
-      }
-    }
-  `;
-};
+const getProgressAnimation = ({ progress }: { progress: number }): CssChild =>
+  atRule(
+    '@keyframes rankAnimation',
+    rule('from', { 'stroke-dashoffset': calculateCircleProgress(0) }),
+    rule('to', { 'stroke-dashoffset': calculateCircleProgress(progress) }),
+  );
 
 /**
  * Retrieves CSS styles for a card.
  *
- * @param colors The colors to use for the card.
- * @param colors.textColor The text color.
- * @param colors.iconColor The icon color.
- * @param colors.ringColor The ring color.
- * @param colors.show_icons Whether to show icons.
- * @param colors.progress The progress value to animate to.
  * @returns Card CSS styles.
  */
 const getStyles = ({
@@ -146,64 +139,56 @@ const getStyles = ({
   ringColor: string;
   show_icons: boolean;
   progress: number;
-}): string => {
-  return `
-    .stat {
-      font: 600 14px 'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif; fill: ${textColor};
-    }
-    @supports(-moz-appearance: auto) {
-      /* Selector detects Firefox */
-      .stat { font-size:12px; }
-    }
-    .stagger {
-      opacity: 0;
-      animation: fadeInAnimation 0.3s ease-in-out forwards;
-    }
-    .rank-text {
-      font: 800 24px 'Segoe UI', Ubuntu, Sans-Serif; fill: ${textColor};
-      animation: scaleInAnimation 0.3s ease-in-out forwards;
-    }
-    .rank-percentile-header {
-      font-size: 14px;
-    }
-    .rank-percentile-text {
-      font-size: 16px;
-    }
-    
-    .not_bold { font-weight: 400 }
-    .bold { font-weight: 700 }
-    .icon {
-      fill: ${iconColor};
-      display: ${show_icons ? 'block' : 'none'};
-    }
-
-    .rank-circle-rim {
-      stroke: ${ringColor};
-      fill: none;
-      stroke-width: 6;
-      opacity: 0.2;
-    }
-    .rank-circle {
-      stroke: ${ringColor};
-      stroke-dasharray: 250;
-      fill: none;
-      stroke-width: 6;
-      stroke-linecap: round;
-      opacity: 0.8;
-      transform-origin: -10px 8px;
-      transform: rotate(-90deg);
-      animation: rankAnimation 1s forwards ease-in-out;
-    }
-    ${getProgressAnimation({ progress })}
-  `;
-};
+}): Array<CssChild> => [
+  rule('.stat', {
+    font: `400 ${STAT_FONT_SIZE}px 'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif`,
+    fill: textColor,
+    'font-variant-numeric': 'tabular-nums',
+  }),
+  atRule(
+    '@supports(-moz-appearance: auto)',
+    cssComment('Selector detects Firefox'),
+    rule('.stat', { 'font-size': '12px' }),
+  ),
+  rule('.stagger', { opacity: 0, animation: 'fadeInAnimation 0.3s ease-in-out forwards' }),
+  rule('.rank-text', {
+    font: "700 22px 'Segoe UI', Ubuntu, Sans-Serif",
+    fill: textColor,
+    animation: 'scaleInAnimation 0.3s ease-in-out forwards',
+  }),
+  rule('.rank-percentile-header', { 'font-size': '14px' }),
+  rule('.rank-percentile-text', { 'font-size': '16px' }),
+  cssComment('Labels recede so that the values read first.'),
+  rule('.not_bold', { 'font-weight': 400, opacity: 0.75 }),
+  rule('.bold', { 'font-weight': 600 }),
+  rule('.icon', {
+    fill: iconColor,
+    opacity: 0.75,
+    display: show_icons ? 'block' : 'none',
+  }),
+  rule('.rank-circle-rim', {
+    stroke: ringColor,
+    fill: 'none',
+    'stroke-width': 4,
+    opacity: 0.15,
+  }),
+  rule('.rank-circle', {
+    stroke: ringColor,
+    'stroke-dasharray': 250,
+    fill: 'none',
+    'stroke-width': 4,
+    'stroke-linecap': 'round',
+    opacity: 1,
+    'transform-origin': '-10px 8px',
+    transform: 'rotate(-90deg)',
+    animation: 'rankAnimation 0.8s forwards ease-in-out',
+  }),
+  getProgressAnimation({ progress }),
+];
 
 /**
  * Return the label for commits according to the selected options
  *
- * @param include_all_commits Option to include all years
- * @param commits_year Option to include only selected year
- * @param i18n The I18n instance.
  * @returns The label corresponding to the options.
  */
 const getTotalCommitsYearLabel = (
@@ -220,11 +205,6 @@ const getTotalCommitsYearLabel = (
 /**
  * Renders the stats card.
  *
- * @param stats The stats data.
- * @param options The card options.
- * @param username GitHub username, used to build stat search links.
- * @param repo Repositories to scope the search links to.
- * @param owner Owners to scope the search links to.
  * @returns The stats card SVG object.
  */
 const renderStatsCard = (
@@ -276,7 +256,7 @@ const renderStatsCard = (
     show = [],
   } = options;
 
-  const lheight = parseInt(String(line_height), 10);
+  const lheight = Number.parseInt(String(line_height), 10);
 
   const { lightColors, darkColors } = getLightDarkColors(options);
 
@@ -290,13 +270,13 @@ const renderStatsCard = (
   });
 
   // Meta data for creating text nodes with createTextNode function
-  const STATS: Record<string, StatItem> = {};
-
-  STATS['stars'] = {
-    icon: icons.star,
-    label: i18n.t('statcard.totalstars'),
-    value: totalStars,
-    id: 'stars',
+  const STATS: Record<string, StatItem> = {
+    stars: {
+      icon: icons.star,
+      label: i18n.t('statcard.totalstars'),
+      value: totalStars,
+      id: 'stars',
+    },
   };
 
   if (show.includes('contributions')) {
@@ -445,88 +425,96 @@ const renderStatsCard = (
     };
   }
 
-  const isLongLocale = locale ? LONG_LOCALES.includes(locale) : false;
+  const isLongLocale = locale ? LONG_LOCALES.has(locale) : false;
 
-  // check if all used labels are short
-  const longLabels = Object.entries(STATS)
-    .filter(([key]) => !hide.includes(key))
-    .some(([, stat]) => stat.label.length > 18);
-
-  // filter out hidden stats defined by user & create the text nodes
-  const statItems = Object.entries(STATS)
-    .filter(([key]) => !hide.includes(key))
-    // pass index so that we can calculate the line spacing
-    .map(([, stat], index) =>
-      createTextNode({
-        icon: stat.icon,
-        label: stat.label,
-        value: stat.value,
-        id: stat.id,
-        unitSymbol: stat.unitSymbol,
-        index,
-        showIcons: show_icons,
-        shiftValuePos: 29.01 + (longLabels ? 50 : 0) + (isLongLocale ? 50 : 0),
-        bold: text_bold,
-        numberFormat: number_format,
-        numberPrecision: number_precision,
-        link: stat.link,
-      }),
-    );
+  // filter out hidden stats defined by user
+  const visibleStats = Object.entries(STATS).filter(([key]) => !hide.includes(key));
 
-  if (statItems.length === 0 && hide_rank) {
+  if (visibleStats.length === 0 && hide_rank) {
     throw new CardError('Could not render stats card.', {
       code: 'invalid_param',
       secondaryMessage: 'Either stats or rank are required.',
     });
   }
 
-  // Calculate the card height depending on how many items there are
-  // but if rank circle is visible clamp the minimum height to `150`
+  // check if all used labels are short
+  const longLabels = visibleStats.some(([, stat]) => stat.label.length > 18);
+
+  // The rank ring sets the floor: 150 beside the stats, 180 when it is the whole card.
   const height = Math.max(
-    45 + (statItems.length + 1) * lheight,
-    hide_rank ? 0 : statItems.length ? 150 : 180,
+    45 + (visibleStats.length + 1) * lheight,
+    hide_rank ? 0 : visibleStats.length > 0 ? 150 : 180,
   );
 
   // the lower the user's percentile the better
   const progress = 100 - rank.percentile;
 
-  const calculateTextWidth = () => {
-    return measureText(
-      custom_title
-        ? custom_title
-        : statItems.length
-          ? i18n.t('statcard.title')
-          : i18n.t('statcard.ranktitle'),
+  const calculateTextWidth = (): number =>
+    measureText(
+      custom_title ||
+        (visibleStats.length > 0 ? i18n.t('statcard.title') : i18n.t('statcard.ranktitle')),
     );
-  };
 
   /*
     When hide_rank=true, the minimum card width is 270 px + the title length and padding.
     When hide_rank=false, the minimum card_width is 340 px + the icon width (if show_icons=true).
     Numbers are picked by looking at existing dimensions on production.
   */
-  const iconWidth = show_icons && statItems.length ? 16 + /* padding */ 1 : 0;
+  const iconWidth = show_icons && visibleStats.length > 0 ? 16 + /* padding */ 1 : 0;
   const minCardWidth =
     (hide_rank
       ? clampValue(50 /* padding */ + calculateTextWidth() * 2, CARD_MIN_WIDTH, Infinity)
-      : statItems.length
+      : visibleStats.length > 0
         ? RANK_CARD_MIN_WIDTH
         : RANK_ONLY_CARD_MIN_WIDTH) + iconWidth;
   const defaultCardWidth =
     (hide_rank
       ? CARD_DEFAULT_WIDTH
-      : statItems.length
+      : visibleStats.length > 0
         ? RANK_CARD_DEFAULT_WIDTH
         : RANK_ONLY_CARD_DEFAULT_WIDTH) + iconWidth;
   const width = card_width
-    ? isNaN(card_width)
+    ? Number.isNaN(card_width)
       ? Math.max(defaultCardWidth, minCardWidth)
       : card_width
     : Math.max(defaultCardWidth, minCardWidth);
 
+  // A value ends at the card's inner edge, clear of the rank ring — or right after
+  // the longest label, on a card too narrow for that.
+  const widestLabel =
+    visibleStats.length > 0
+      ? Math.max(...visibleStats.map(([, stat]) => measureText(`${stat.label}:`, STAT_FONT_SIZE)))
+      : 0;
+  const valueAnchorX = Math.round(
+    Math.max(
+      width - CARD_PADDING_X - STAT_ROW_X - (hide_rank ? 0 : RANK_GUTTER),
+      (show_icons ? LABEL_X_OFFSET : 0) + widestLabel + LABEL_VALUE_GAP,
+    ),
+  );
+
+  // pass index so that we can calculate the line spacing
+  const statItems = visibleStats.map(([, stat], index) =>
+    createTextNode({
+      icon: stat.icon,
+      label: stat.label,
+      value: stat.value,
+      id: stat.id,
+      unitSymbol: stat.unitSymbol,
+      index,
+      showIcons: show_icons,
+      shiftValuePos: 29.01 + (longLabels ? 50 : 0) + (isLongLocale ? 50 : 0),
+      valueAnchorX,
+      bold: text_bold,
+      labelBold: false,
+      numberFormat: number_format,
+      numberPrecision: number_precision,
+      link: stat.link,
+    }),
+  );
+
   const card = new Card({
     customTitle: custom_title,
-    defaultTitle: statItems.length ? i18n.t('statcard.title') : i18n.t('statcard.ranktitle'),
+    defaultTitle: visibleStats.length > 0 ? i18n.t('statcard.title') : i18n.t('statcard.ranktitle'),
     width,
     height,
     border_radius,
@@ -535,7 +523,7 @@ const renderStatsCard = (
 
   card.setHideBorder(hide_border);
   card.setHideTitle(hide_title);
-  const cardStyles = ({ ringColor, textColor, iconColor }: CardColors): string =>
+  const cardStyles = ({ ringColor, textColor, iconColor }: CardColors): Array<CssChild> =>
     getStyles({ ringColor, textColor, iconColor, show_icons, progress });
 
   card.setCSS({ light: cardStyles, dark: cardStyles });
@@ -555,34 +543,33 @@ const renderStatsCard = (
    * @returns Rank circle translation value.
    */
   const calculateRankXTranslation = (): number => {
-    if (statItems.length) {
+    if (visibleStats.length > 0) {
       const minXTranslation = RANK_CARD_MIN_WIDTH + iconWidth - 70;
       if (width > RANK_CARD_DEFAULT_WIDTH) {
         const xMaxExpansion = minXTranslation + (450 - minCardWidth) / 2;
         return xMaxExpansion + width - RANK_CARD_DEFAULT_WIDTH;
-      } else {
-        return minXTranslation + (width - minCardWidth) / 2;
       }
-    } else {
-      return width / 2 + 20 - 10;
+      return minXTranslation + (width - minCardWidth) / 2;
     }
+    return width / 2 + 20 - 10;
   };
 
   // Conditionally rendered elements
-  const rankCircle = hide_rank
-    ? ''
-    : `<g data-testid="rank-circle"
-          transform="translate(${calculateRankXTranslation()}, ${height / 2 - 50})">
-        <circle class="rank-circle-rim" cx="-10" cy="8" r="40" />
-        <circle class="rank-circle" cx="-10" cy="8" r="40" />
-        <g class="rank-text">
-          ${rankIcon(rank_icon, rank.level, rank.percentile)}
-        </g>
-      </g>`;
+  const rankCircle =
+    !hide_rank &&
+    el(
+      'g',
+      {
+        'data-testid': 'rank-circle',
+        transform: `translate(${calculateRankXTranslation()}, ${height / 2 - 50})`,
+      },
+      el('circle', { class: 'rank-circle-rim', cx: -10, cy: 8, r: 40 }),
+      el('circle', { class: 'rank-circle', cx: -10, cy: 8, r: 40 }),
+      el('g', { class: 'rank-text' }, rankIcon(rank_icon, rank.level, rank.percentile)),
+    );
 
   // Accessibility Labels
-  const labels = Object.entries(STATS)
-    .filter(([key]) => !hide.includes(key))
+  const labels = visibleStats
     .map(([key, stat]) => {
       if (key === 'commits') {
         return `${i18n.t('statcard.commits')} ${getTotalCommitsYearLabel(
@@ -600,16 +587,10 @@ const renderStatsCard = (
     desc: labels,
   });
 
-  return card.render(`
-    ${rankCircle}
-    <svg x="0" y="0">
-      ${flexLayout({
-        items: statItems,
-        gap: lheight,
-        direction: 'column',
-      }).join('')}
-    </svg>
-  `);
+  return card.render([
+    rankCircle,
+    el('svg', { x: 0, y: 0 }, flexLayout({ items: statItems, gap: lheight, direction: 'column' })),
+  ]);
 };
 
 export { RANK_ICONS, renderStatsCard };