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

package/src/api/wakatime.ts

@@ -1,12 +1,9 @@
 import * as z from 'zod/mini';
 
-import { DISPLAY_FORMATS, WAKATIME_LAYOUTS, renderWakatimeCard } from '../cards/wakatime.ts';
-import type { CardConfig } from '../common/config.ts';
+import { renderWakatimeCard } from '../cards/wakatime.ts';
 import { fetchWakatimeStats } from '../fetchers/wakatime.ts';
 
-import type { ApiResult } from './api-result.ts';
-import { errorResult } from './api-result.ts';
-import type { ApiQuery } from './params.ts';
+import { cardHandler } from './handler.ts';
 import {
   booleanParam,
   enumParam,
@@ -14,8 +11,6 @@ import {
   localeParam,
   looseIntParam,
   numberParam,
-  parseColorParams,
-  parseParams,
   rawParam,
   safeParam,
 } from './params.ts';
@@ -30,18 +25,15 @@ const wakatimeQuery = z.object({
   hide_progress: booleanParam,
   custom_title: rawParam,
   locale: localeParam,
-  layout: enumParam(WAKATIME_LAYOUTS),
+  layout: enumParam(renderWakatimeCard.OPTIONS.layout),
   langs_count: looseIntParam,
   hide: listParam,
   api_domain: rawParam,
   border_radius: numberParam,
-  display_format: enumParam(DISPLAY_FORMATS),
+  display_format: enumParam(renderWakatimeCard.OPTIONS.display_format),
   disable_animations: booleanParam,
 });
 
-/** The query this endpoint accepts, checked against the schema above. */
-type WakatimeApiQuery = ApiQuery<typeof wakatimeQuery>;
-
 /**
  * Render the WakaTime card for a set of query params.
  *
@@ -49,17 +41,10 @@ type WakatimeApiQuery = ApiQuery<typeof wakatimeQuery>;
  *
  * @returns The rendered card, or a rendered error.
  */
-const renderWakatime = async (query: WakatimeApiQuery, config: CardConfig): Promise<ApiResult> => {
-  let colors;
-  try {
-    colors = parseColorParams(query);
-  } catch (error) {
-    // A rejected color cannot be used to draw its own error card.
-    return errorResult(error);
-  }
-
-  try {
-    const {
+const renderWakatime = cardHandler(
+  wakatimeQuery,
+  async (
+    {
       username,
       hide_border,
       card_width,
@@ -75,39 +60,33 @@ const renderWakatime = async (query: WakatimeApiQuery, config: CardConfig): Prom
       border_radius,
       display_format,
       disable_animations,
-    } = parseParams(wakatimeQuery, query);
-
+    },
+    colors,
+    config,
+  ) => {
     const stats = await fetchWakatimeStats({ username, api_domain }, config);
 
-    return {
-      status: 'success',
-      content: renderWakatimeCard(stats, {
-        ...colors,
-        custom_title,
-        hide_title,
-        hide_border,
-        card_width,
-        hide,
-        line_height,
-        hide_progress,
-        border_radius,
-        locale,
-        layout,
-        langs_count,
-        display_format,
-        disable_animations,
-      }),
-    };
-  } catch (error) {
-    return errorResult(error, colors);
-  }
-};
+    return renderWakatimeCard(stats, {
+      ...colors,
+      custom_title,
+      hide_title,
+      hide_border,
+      card_width,
+      hide,
+      line_height,
+      hide_progress,
+      border_radius,
+      locale,
+      layout,
+      langs_count,
+      display_format,
+      disable_animations,
+    });
+  },
+);
 
 /**
- * The card, with the values its enum params accept.
- * A UI reads them off the function it calls, e.g. `wakatime.LAYOUTS`.
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * A UI reads them off the function it calls: `wakatime.OPTIONS.layout`.
  */
-export const wakatime = Object.assign(renderWakatime, {
-  LAYOUTS: WAKATIME_LAYOUTS,
-  DISPLAY_FORMATS,
-});
+export const wakatime = Object.assign(renderWakatime, { OPTIONS: renderWakatimeCard.OPTIONS });

package/src/cards/contributed-to.ts

@@ -0,0 +1,373 @@
+import { CARD_ICON, CARD_WIDTH, FONT_SIZE, firefoxFontSize, font } from '../common/brand.ts';
+import { Card } from '../common/Card.ts';
+import { getLightDarkColors } from '../common/color.ts';
+import { formatYears } from '../common/date.ts';
+import { kFormatter } from '../common/fmt.ts';
+import { I18n } from '../common/I18n.ts';
+import { clampValue } from '../common/ops.ts';
+import { createProgressNode, measureText } from '../common/render.ts';
+import type { ContributedRepo, ContributedToData } from '../fetchers/types.ts';
+import type { Child } from '../markup/index.ts';
+import { atRule, el, rule } from '../markup/index.ts';
+import { contributedToCardLocales } from '../translations.ts';
+
+import type { CardOptions, CommonCardOptions } from './options.ts';
+
+const CARD_DEFAULT_WIDTH = CARD_WIDTH.wide;
+const MIN_CARD_WIDTH = 340;
+/** Padding the card keeps at its edges; matches `Card`'s own `paddingX`. */
+const CARD_PADDING = 25;
+
+const TITLE_FONT_SIZE = FONT_SIZE.title;
+/** What `Card`'s title layout reserves for the prefix icon, so the title text starts past it. */
+const TITLE_ICON_COLUMN = 25;
+const NAME_FONT_SIZE = FONT_SIZE.meta;
+
+/** Room kept at the right edge for the contribution count. */
+const COUNT_WIDTH = 46;
+const BAR_WIDTH = 130;
+const COLUMN_GAP = 12;
+
+/** Baseline of the first row, measured from the top of the card body. */
+const FIRST_ROW_Y = 10;
+const ROW_HEIGHT = 38;
+/** A row with no year marks under it needs only its own line. */
+const ROW_HEIGHT_NO_YEARS = 24;
+/** How far the year marks sit below their row's baseline. */
+const YEAR_STRIP_Y = 8;
+const YEAR_MARK_SIZE = 7;
+const YEAR_MARK_GAP = 3;
+
+/** Gap between the last row and the footer's own baseline. */
+const FOOTER_GAP = 12;
+/** Where `Card` puts the body while the title is shown; `setHideTitle` adjusts the height by the same 30. */
+const BODY_OFFSET_Y = 55;
+const BOTTOM_PADDING = 18;
+
+interface ContributedToCardOptions extends CommonCardOptions {
+  locale: string;
+  hide_title: boolean;
+  card_width: number;
+  custom_title: string;
+  disable_animations: boolean;
+  hide_years: boolean;
+}
+
+/** The card's own translation table, so `t` is checked against the keys it declares. */
+type ContributedToI18n = I18n<ReturnType<typeof contributedToCardLocales>>;
+
+/**
+ * The title, naming the account unless that makes it too wide for the card.
+ *
+ * A login is up to 39 characters, which at the title's size overruns the default width
+ * by half again — so the plain wording is the fallback rather than a truncated login.
+ *
+ * @returns The default title, which `custom_title` still overrides.
+ */
+const defaultTitleFor = (i18n: ContributedToI18n, contentWidth: number): string => {
+  const named = i18n.t('contributedtocard.title');
+  return measureText(named, TITLE_FONT_SIZE) <= contentWidth
+    ? named
+    : i18n.t('contributedtocard.title-unnamed');
+};
+
+/**
+ * Shortens a name to fit its column, ending it with an ellipsis when it does not.
+ *
+ * @returns The name as it is drawn.
+ */
+const truncateName = (name: string, maxWidth: number): string => {
+  if (measureText(name, NAME_FONT_SIZE) <= maxWidth) {
+    return name;
+  }
+
+  let trimmed = name;
+  while (trimmed.length > 1 && measureText(`${trimmed}…`, NAME_FONT_SIZE) > maxWidth) {
+    trimmed = trimmed.slice(0, -1);
+  }
+  return `${trimmed}…`;
+};
+
+/**
+ * The marks under a repository's name, one per contribution year of the account,
+ * filled for the years that repository got a contribution.
+ *
+ * The step shrinks to fit, so a long-lived account keeps the strip inside its column
+ * rather than running it under the bar.
+ *
+ * @returns The strip, positioned relative to its row's baseline.
+ */
+const createYearStrip = (
+  repoYears: Array<number>,
+  years: Array<number>,
+  columnWidth: number,
+): Child => {
+  const contributed = new Set(repoYears);
+  const step = Math.min(YEAR_MARK_SIZE + YEAR_MARK_GAP, Math.floor(columnWidth / years.length));
+  const size = Math.max(step - YEAR_MARK_GAP, 3);
+
+  return el(
+    'g',
+    { 'data-testid': 'year-strip', transform: `translate(0, ${YEAR_STRIP_Y})` },
+    years.map((year, index) =>
+      el('rect', {
+        'data-testid': contributed.has(year) ? 'year-on' : 'year-off',
+        class: contributed.has(year) ? 'year-on' : 'year-off',
+        x: index * step,
+        y: 0,
+        width: size,
+        height: size,
+        rx: 1,
+        ry: 1,
+      }),
+    ),
+  );
+};
+
+/**
+ * One repository: its name, a bar for its share of the top repository's contributions,
+ * and the count itself.
+ *
+ * @returns The row, positioned by its own transform.
+ */
+const createRepoRow = ({
+  repo,
+  index,
+  maxContributions,
+  years,
+  nameWidth,
+  contentWidth,
+  rowHeight,
+}: {
+  repo: ContributedRepo;
+  index: number;
+  maxContributions: number;
+  /** Empty when the year marks are hidden. */
+  years: Array<number>;
+  nameWidth: number;
+  contentWidth: number;
+  rowHeight: number;
+}): Child =>
+  el(
+    'g',
+    {
+      class: 'stagger',
+      style: `animation-delay: ${450 + index * 150}ms`,
+      transform: `translate(0, ${FIRST_ROW_Y + index * rowHeight})`,
+    },
+    el(
+      'text',
+      { class: 'repo-name', 'data-testid': 'repo-name', x: 0, y: 0 },
+      truncateName(repo.nameWithOwner, nameWidth),
+    ),
+    createProgressNode({
+      x: nameWidth + COLUMN_GAP,
+      y: -9,
+      width: BAR_WIDTH,
+      progress: (repo.contributions / maxContributions) * 100,
+      delay: 450 + index * 150,
+    }),
+    el(
+      'text',
+      {
+        class: 'count',
+        'data-testid': 'repo-contributions',
+        x: contentWidth,
+        y: 0,
+        'text-anchor': 'end',
+      },
+      kFormatter(repo.contributions),
+    ),
+    years.length > 0 && createYearStrip(repo.years, years, nameWidth),
+  );
+
+/**
+ * The line under the rows: how much of the walk the card is showing, and over what years.
+ *
+ * Never dropped, because the card shows a slice of the repositories
+ * and a rank means nothing without the total it was taken from.
+ *
+ * @returns The footer text.
+ */
+const footerText = ({
+  i18n,
+  shown,
+  totalRepos,
+  years,
+}: {
+  i18n: ContributedToI18n;
+  shown: number;
+  totalRepos: number;
+  /** Empty when the year marks are hidden, which is what puts the years on the card. */
+  years: Array<number>;
+}): string => {
+  const parts = [
+    i18n.t(shown < totalRepos ? 'contributedtocard.footer-top' : 'contributedtocard.footer-all'),
+  ];
+
+  const [firstYear] = years;
+  const lastYear = years.at(-1);
+  if (firstYear !== undefined && lastYear !== undefined) {
+    parts.push(formatYears(firstYear, lastYear));
+  }
+
+  return parts.join(' · ');
+};
+
+/**
+ * Renders the repositories a user contributed to, ranked by contributions.
+ *
+ * @returns Contributed-to card SVG string.
+ */
+const renderContributedToCard = (
+  data: ContributedToData,
+  options: CardOptions<ContributedToCardOptions> = {},
+): string => {
+  const {
+    locale,
+    hide_title = false,
+    hide_border = false,
+    card_width,
+    custom_title,
+    disable_animations = false,
+    hide_years = false,
+    border_radius,
+    theme = 'default',
+  } = options;
+
+  const { login, repos, totalRepos } = data;
+  const years = hide_years ? [] : data.years;
+
+  const width =
+    card_width && !Number.isNaN(card_width)
+      ? clampValue(card_width, MIN_CARD_WIDTH, Number.MAX_SAFE_INTEGER)
+      : CARD_DEFAULT_WIDTH;
+  const contentWidth = width - 2 * CARD_PADDING;
+  const nameWidth = contentWidth - COUNT_WIDTH - BAR_WIDTH - 2 * COLUMN_GAP;
+
+  const rowHeight = years.length > 0 ? ROW_HEIGHT : ROW_HEIGHT_NO_YEARS;
+  // the count is a share of the busiest repository, so the first bar is always full
+  const maxContributions = Math.max(...repos.map((repo) => repo.contributions), 1);
+
+  const rows = repos.map((repo, index) =>
+    createRepoRow({
+      repo,
+      index,
+      maxContributions,
+      years,
+      nameWidth,
+      contentWidth,
+      rowHeight,
+    }),
+  );
+
+  const i18n = new I18n({
+    locale,
+    translations: contributedToCardLocales({ login, shown: repos.length, totalRepos }),
+  });
+
+  const footer = footerText({ i18n, shown: repos.length, totalRepos, years });
+  const footerY = FIRST_ROW_Y + Math.max(repos.length, 1) * rowHeight + FOOTER_GAP;
+  const height = BODY_OFFSET_Y + footerY + BOTTOM_PADDING;
+
+  const { lightColors, darkColors } = getLightDarkColors({ ...options, theme });
+
+  const card = new Card({
+    customTitle: custom_title,
+    defaultTitle: defaultTitleFor(i18n, contentWidth - TITLE_ICON_COLUMN),
+    titlePrefixIcon: CARD_ICON.contributedTo,
+    width,
+    height,
+    border_radius,
+    colors: { light: lightColors, dark: darkColors },
+  });
+
+  if (disable_animations) {
+    card.disableAnimations();
+  }
+
+  card.setHideBorder(hide_border);
+  card.setHideTitle(hide_title);
+  card.setCSS({
+    light: ({ textColor, titleColor, iconColor, progBarBgColor }) => [
+      atRule(
+        '@keyframes growWidthAnimation',
+        rule('from', { width: 0 }),
+        rule('to', { width: '100%' }),
+      ),
+      rule('.repo-name', {
+        font: font('regular', 'meta'),
+        fill: textColor,
+      }),
+      rule('.count', {
+        font: font('semibold', 'meta'),
+        fill: textColor,
+        'font-variant-numeric': 'tabular-nums',
+      }),
+      rule('.footer', {
+        font: font('regular', 'micro'),
+        fill: textColor,
+        opacity: 0.7,
+      }),
+      firefoxFontSize(['.repo-name', '.count'], 'small'),
+      rule('.year-on', { fill: titleColor }),
+      // a year with no contribution reads off the text color, not `progBarBgColor`:
+      // on a dark theme that color is a light grey, and the empty marks came out looking filled
+      rule('.year-off', { fill: textColor, opacity: 0.25 }),
+      rule('.progress-background', { fill: progBarBgColor }),
+      rule('.lang-progress', {
+        fill: titleColor,
+        animation: 'growWidthAnimation 0.6s ease-in-out forwards',
+      }),
+      rule('.stagger', { opacity: 0, animation: 'fadeInAnimation 0.3s ease-in-out forwards' }),
+      rule('.icon', { fill: iconColor, display: 'block' }),
+    ],
+    dark: ({ textColor, titleColor, iconColor, progBarBgColor }) => [
+      rule('.repo-name', { fill: textColor }),
+      rule('.count', { fill: textColor }),
+      rule('.footer', { fill: textColor }),
+      rule('.year-on', { fill: titleColor }),
+      // a year with no contribution reads off the text color, not `progBarBgColor`:
+      // on a dark theme that color is a light grey, and the empty marks came out looking filled
+      rule('.year-off', { fill: textColor, opacity: 0.25 }),
+      rule('.progress-background', { fill: progBarBgColor }),
+      rule('.lang-progress', { fill: titleColor }),
+      rule('.icon', { fill: iconColor }),
+    ],
+  });
+
+  // `role="img"` hides the inner text from assistive tech, so everything the card
+  // shows has to be repeated here — the year marks included, since they carry
+  // information no other element on the card does.
+  card.setAccessibilityLabel({
+    title: card.title,
+    desc: [
+      ...repos.map((repo) => {
+        const inYears = hide_years
+          ? ''
+          : `, ${i18n.t('contributedtocard.years')}: ${repo.years.join(', ')}`;
+        return `${repo.nameWithOwner}: ${repo.contributions} ${i18n.t(
+          'contributedtocard.contributions',
+        )}${inYears}`;
+      }),
+      footer,
+    ].join('; '),
+  });
+
+  return card.render(
+    el(
+      'g',
+      { 'data-testid': 'contributed-to-body', transform: `translate(${CARD_PADDING}, 0)` },
+      repos.length === 0
+        ? el(
+            'text',
+            { class: 'repo-name', 'data-testid': 'no-repos', x: 0, y: FIRST_ROW_Y },
+            i18n.t('contributedtocard.no-contributions'),
+          )
+        : rows,
+      el('text', { class: 'footer', 'data-testid': 'footer', x: 0, y: footerY }, footer),
+    ),
+  );
+};
+
+export { renderContributedToCard, MIN_CARD_WIDTH };

package/src/cards/gist.ts

@@ -1,6 +1,8 @@
+import { CARD_ICON, CARD_WIDTH, FONT_SIZE, font } from '../common/brand.ts';
 import { Card } from '../common/Card.ts';
 import { getLightDarkColors } from '../common/color.ts';
 import { kFormatter } from '../common/fmt.ts';
+import { I18n } from '../common/I18n.ts';
 import { icons } from '../common/icons.ts';
 import { getLanguageColor } from '../common/languageColors.ts';
 import { parseEmojis } from '../common/ops.ts';
@@ -17,19 +19,21 @@ import {
 import type { GistData } from '../fetchers/types.ts';
 import type { Child } from '../markup/index.ts';
 import { el, rule } from '../markup/index.ts';
+import { gistCardLocales } from '../translations.ts';
 
 import type { CardOptions, CommonCardOptions } from './options.ts';
 
 const ICON_SIZE = 16;
-const CARD_DEFAULT_WIDTH = 400;
+const CARD_DEFAULT_WIDTH = CARD_WIDTH.standard;
 const X_OFFSET = 25;
 const HEADER_MAX_LENGTH = 35;
 const DESCRIPTION_BOX_WIDTH = CARD_DEFAULT_WIDTH - 2 * X_OFFSET;
-const DESCRIPTION_FONT_SIZE = 13;
+const DESCRIPTION_FONT_SIZE = FONT_SIZE.meta;
 const DESCRIPTION_LINE_HEIGHT_PX = 16;
 const DESCRIPTION_MAX_LINES = 10;
 
 interface GistCardOptions extends CommonCardOptions {
+  locale: string;
   show_owner: boolean;
   browser_rendering: boolean;
 }
@@ -42,6 +46,7 @@ interface GistCardOptions extends CommonCardOptions {
 const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions> = {}): string => {
   const { name, nameWithOwner, description, language, starsCount, forksCount } = gistData;
   const {
+    locale,
     theme = 'default_repocard',
     border_radius,
     show_owner = false,
@@ -51,7 +56,9 @@ const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions
 
   const { lightColors, darkColors } = getLightDarkColors({ ...options, theme });
 
-  const desc = parseEmojis(description || 'No description provided');
+  const i18n = new I18n({ locale, translations: gistCardLocales });
+
+  const desc = parseEmojis(description || i18n.t('gistcard.no-description'));
 
   let descriptionLines: number;
   let descriptionSvg: Child;
@@ -101,7 +108,7 @@ const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions
   const svgStars = iconWithLabel(icons.star, totalStars, 'starsCount', ICON_SIZE);
   const svgForks = iconWithLabel(icons.fork, totalForks, 'forksCount', ICON_SIZE);
 
-  const languageName = language || 'Unspecified';
+  const languageName = language || i18n.t('gistcard.unspecified-language');
   const languageColor = getLanguageColor(languageName);
 
   const svgLanguage = createLanguageNode(languageName, languageColor);
@@ -121,7 +128,7 @@ const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions
   const card = new Card({
     defaultTitle:
       header.length > HEADER_MAX_LENGTH ? `${header.slice(0, HEADER_MAX_LENGTH)}...` : header,
-    titlePrefixIcon: icons.gist,
+    titlePrefixIcon: CARD_ICON.gist,
     width: CARD_DEFAULT_WIDTH,
     height,
     border_radius,
@@ -131,11 +138,11 @@ const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions
   card.setCSS({
     light: ({ textColor, iconColor }) => [
       rule('.description', {
-        font: `400 ${DESCRIPTION_FONT_SIZE}px 'Segoe UI', Ubuntu, Sans-Serif`,
+        font: font('regular', 'meta'),
         fill: textColor,
         ...(browser_rendering ? wrappedTextStyles(textColor) : {}),
       }),
-      rule('.gray', { font: "400 12px 'Segoe UI', Ubuntu, Sans-Serif", fill: textColor }),
+      rule('.gray', { font: font('regular', 'small'), fill: textColor }),
       rule('.icon', { fill: iconColor }),
     ],
     dark: ({ textColor, iconColor }) => [
@@ -154,7 +161,9 @@ const renderGistCard = (gistData: GistData, options: CardOptions<GistCardOptions
   // shows has to be repeated here.
   card.setAccessibilityLabel({
     title: card.title,
-    desc: `${desc}. Language: ${languageName}, Stars: ${totalStars}, Forks: ${totalForks}`,
+    desc: `${desc}. ${i18n.t('gistcard.language')}: ${languageName}, ${i18n.t(
+      'gistcard.stars',
+    )}: ${totalStars}, ${i18n.t('gistcard.forks')}: ${totalForks}`,
   });
 
   return card.render([