@stats-organization/github-readme-stats-core 2.1.5 → 2.2.0

package/src/common/Card.ts

@@ -1,18 +1,18 @@
-import { isPrefixedHexColor, isValidGradient } from "./color.js";
+import { getCardColors, isPrefixedHexColor, isValidGradient } from "./color.js";
 import { encodeHTML } from "./html.js";
 import { flexLayout } from "./render.js";
 
 interface CardColors {
   /** Card title color. */
-  titleColor?: string;
+  titleColor: string;
   /** Card text color. */
-  textColor?: string;
+  textColor: string;
   /** Card icon color. */
-  iconColor?: string;
+  iconColor: string;
   /** Card background color. */
-  bgColor?: string | Array<string>;
+  bgColor: string | Array<string>;
   /** Card border color. */
-  borderColor?: string;
+  borderColor: string;
 }
 
 class Card {
@@ -21,9 +21,10 @@ class Card {
   hideBorder: boolean;
   hideTitle: boolean;
   border_radius: number;
-  colors: CardColors;
+  colors: { light: CardColors; dark: CardColors | null };
   title: string;
   css: string;
+  darkCss: string;
   paddingX: number;
   paddingY: number;
   titlePrefixIcon: string | undefined;
@@ -40,7 +41,9 @@ class Card {
    * @param props.width Card width.
    * @param props.height Card height.
    * @param props.border_radius Card border radius.
-   * @param props.colors Card colors arguments.
+   * @param props.colors Card colors for light and dark mode.
+   * @param props.colors.light Card colors for light mode.
+   * @param props.colors.dark Card colors for dark mode, or `null` when no dark-mode override is needed.
    * @param props.customTitle Card custom title.
    * @param props.defaultTitle Card default title.
    * @param props.titlePrefixIcon Sanitized card title prefix icon.
@@ -49,16 +52,17 @@ class Card {
     width = 100,
     height = 100,
     border_radius = 4.5,
-    colors = {},
+    colors = { light: getCardColors({}), dark: null },
     customTitle,
     defaultTitle = "",
     titlePrefixIcon,
   }: {
     width?: number;
     height?: number;
-    border_radius?: number;
-    colors?: CardColors;
-    customTitle?: string;
+    // `| undefined`: card callers forward possibly-undefined query options
+    border_radius?: number | undefined;
+    colors?: { light: CardColors; dark: CardColors | null };
+    customTitle?: string | undefined;
     defaultTitle?: string;
     titlePrefixIcon?: string;
   }) {
@@ -70,11 +74,11 @@ class Card {
 
     this.border_radius = parseFloat(String(border_radius));
 
-    // returns theme based colors with proper overrides and defaults
     this.colors = colors;
     this.title = customTitle === undefined ? defaultTitle : customTitle;
 
     this.css = "";
+    this.darkCss = "";
 
     this.paddingX = 25;
     this.paddingY = 35;
@@ -105,12 +109,17 @@ class Card {
   }
 
   /**
-   * The caller must ensure that the passed `css` string is properly sanitized!
+   * Sets the card CSS for light and dark mode.
    *
-   * @param value The sanitized CSS to add to the card.
+   * The caller must ensure that the passed CSS strings are properly sanitized!
+   *
+   * @param props The props object.
+   * @param props.light CSS applied unconditionally (light/default mode).
+   * @param props.dark CSS placed inside a `@media (prefers-color-scheme: dark)` block. Pass `null` when not needed.
    */
-  setCSS(value: string): void {
-    this.css = value;
+  setCSS({ light, dark }: { light: string; dark?: string | null }): void {
+    this.css = light;
+    this.darkCss = dark ?? "";
   }
 
   /**
@@ -183,19 +192,12 @@ class Card {
    * @returns The rendered card gradient.
    */
   renderGradient(): string {
-    if (typeof this.colors.bgColor !== "object") {
-      return "";
-    }
-    if (!isValidGradient(this.colors.bgColor)) {
-      throw new Error(`Invalid gradient: ${this.colors.bgColor.join(",")}`);
-    }
-
-    const gradients = this.colors.bgColor.slice(1);
-    return `
-        <defs>
+    const buildGradientDef = (id: string, bgColor: Array<string>): string => {
+      const gradients = bgColor.slice(1);
+      return `
           <linearGradient
-            id="gradient"
-            gradientTransform="rotate(${String(this.colors.bgColor[0])})"
+            id="${id}"
+            gradientTransform="rotate(${String(bgColor[0])})"
             gradientUnits="userSpaceOnUse"
           >
             ${gradients
@@ -204,7 +206,31 @@ class Card {
                 return `<stop offset="${offset}%" stop-color="#${grad}" />`;
               })
               .join(",")}
-          </linearGradient>
+          </linearGradient>`;
+    };
+
+    if (
+      typeof this.colors.light.bgColor === "object" &&
+      !isValidGradient(this.colors.light.bgColor)
+    ) {
+      throw new Error(
+        `Invalid gradient: ${this.colors.light.bgColor.join(",")}`,
+      );
+    }
+    if (
+      this.colors.dark &&
+      typeof this.colors.dark.bgColor === "object" &&
+      !isValidGradient(this.colors.dark.bgColor)
+    ) {
+      throw new Error(
+        `Invalid dark gradient: ${this.colors.dark.bgColor.join(",")}`,
+      );
+    }
+
+    return `
+        <defs>
+          ${typeof this.colors.light.bgColor === "object" ? buildGradientDef("gradient", this.colors.light.bgColor) : ""}
+          ${this.colors.dark && typeof this.colors.dark.bgColor === "object" ? buildGradientDef("gradient-dark", this.colors.dark.bgColor) : ""}
         </defs>
         `;
   }
@@ -236,6 +262,28 @@ class Card {
     `;
   };
 
+  /**
+   * Builds the @media (prefers-color-scheme: dark) CSS block for the card.
+   * Returns an empty string when no dark colors are set.
+   */
+  private renderDarkMediaBlock(): string {
+    if (!this.colors.dark) {
+      return "";
+    }
+
+    const bgFill =
+      typeof this.colors.dark.bgColor === "object"
+        ? "url(#gradient-dark)"
+        : this.colors.dark.bgColor;
+
+    return `
+          @media (prefers-color-scheme: dark) {
+            .header { fill: ${this.colors.dark.titleColor}; }
+            .card-bg { fill: ${bgFill}; stroke: ${this.colors.dark.borderColor}; }
+            ${this.darkCss}
+          }`;
+  }
+
   /**
    * The caller must ensure that the passed `body` string is properly sanitized!
    *
@@ -246,26 +294,21 @@ class Card {
     if (!Number.isFinite(this.border_radius)) {
       throw new Error(`Invalid border radius: "${this.border_radius}"`);
     }
-    if (
-      this.colors.titleColor !== undefined &&
-      !isPrefixedHexColor(this.colors.titleColor)
-    ) {
-      throw new Error(`Invalid title color: "${this.colors.titleColor}"`);
+    if (!isPrefixedHexColor(this.colors.light.titleColor)) {
+      throw new Error(`Invalid title color: "${this.colors.light.titleColor}"`);
     }
-    if (
-      this.colors.borderColor !== undefined &&
-      !isPrefixedHexColor(this.colors.borderColor)
-    ) {
-      throw new Error(`Invalid border color: "${this.colors.borderColor}"`);
+    if (!isPrefixedHexColor(this.colors.light.borderColor)) {
+      throw new Error(
+        `Invalid border color: "${this.colors.light.borderColor}"`,
+      );
     }
     if (
-      this.colors.bgColor !== undefined &&
-      !(typeof this.colors.bgColor === "object"
-        ? isValidGradient(this.colors.bgColor)
-        : isPrefixedHexColor(this.colors.bgColor))
+      !(typeof this.colors.light.bgColor === "object"
+        ? isValidGradient(this.colors.light.bgColor)
+        : isPrefixedHexColor(this.colors.light.bgColor))
     ) {
       throw new Error(
-        `Invalid background color: ${String(this.colors.bgColor)}`,
+        `Invalid background color: ${String(this.colors.light.bgColor)}`,
       );
     }
 
@@ -284,7 +327,7 @@ class Card {
         <style>
           .header {
             font: 600 18px 'Segoe UI', Ubuntu, Sans-Serif;
-            fill: ${String(this.colors.titleColor)};
+            fill: ${this.colors.light.titleColor};
             animation: fadeInAnimation 0.8s ease-in-out forwards;
           }
           @supports(-moz-appearance: auto) {
@@ -292,6 +335,7 @@ class Card {
             .header { font-size: 15.5px; }
           }
           ${this.css}
+          ${this.renderDarkMediaBlock()}
 
           ${this.getAnimations()}
           ${
@@ -305,16 +349,17 @@ class Card {
 
         <rect
           data-testid="card-bg"
+          class="card-bg"
           x="0.5"
           y="0.5"
           rx="${this.border_radius}"
           height="99%"
-          stroke="${String(this.colors.borderColor)}"
+          stroke="${this.colors.light.borderColor}"
           width="${this.width - 1}"
           fill="${
-            typeof this.colors.bgColor === "object"
+            typeof this.colors.light.bgColor === "object"
               ? "url(#gradient)"
-              : String(this.colors.bgColor)
+              : this.colors.light.bgColor
           }"
           stroke-opacity="${this.hideBorder ? 0 : 1}"
         />

package/src/common/I18n.ts

@@ -1,9 +1,12 @@
 const FALLBACK_LOCALE = "en";
 
+/** A map of translation keys to per-locale strings. */
+type TranslationsMap = Record<string, Record<string, string>>;
+
 /**
  * I18n translation class.
  */
-class I18n<Translations extends Record<string, Record<string, string>>> {
+class I18n<Translations extends TranslationsMap = TranslationsMap> {
   locale: string;
   translations: Translations;
 
@@ -16,7 +19,8 @@ class I18n<Translations extends Record<string, Record<string, string>>> {
     locale,
     translations,
   }: {
-    locale?: string;
+    // `| undefined`: card callers forward possibly-undefined query options
+    locale?: string | undefined;
     translations: Translations;
   }) {
     this.locale = locale || FALLBACK_LOCALE;

package/src/common/color.ts

@@ -1,4 +1,5 @@
 import { themes } from "../themes/index.js";
+import type { ThemeName } from "../themes/index.js";
 
 /** Matches a 3-, 4-, 6-, or 8-digit hex color with no leading `#`. */
 const HEX_COLOR =
@@ -114,8 +115,38 @@ interface CardColors {
   bgColor: string | Array<string>;
   borderColor: string;
   ringColor: string;
+  progBarBgColor: string;
 }
 
+/**
+ * Every color param a card accepts, before any `_light` / `_dark` suffix.
+ *
+ * Single source of truth: the param types and {@link COLOR_PARAM_KEYS} are all
+ * derived from this, so adding a param here is enough.
+ */
+const BASE_COLOR_KEYS = [
+  "title_color",
+  "icon_color",
+  "text_color",
+  "bg_color",
+  "border_color",
+  "ring_color",
+  "prog_bar_bg_color",
+  "theme",
+] as const;
+
+const THEME_VARIANTS = ["light", "dark"] as const;
+
+type BaseColorKey = (typeof BASE_COLOR_KEYS)[number];
+type ThemeVariant = (typeof THEME_VARIANTS)[number];
+
+/**
+ * Object with all input color params. Not every field is consumed by every card
+ * (e.g. `prog_bar_bg_color` is only used by the top-languages card's `normal`
+ * layout).
+ */
+type ColorInput = Partial<Record<BaseColorKey, string | undefined>>;
+
 /**
  * Returns theme based colors with proper overrides and defaults.
  *
@@ -126,6 +157,7 @@ interface CardColors {
  * @param props.bg_color Card background color.
  * @param props.border_color Card border color.
  * @param props.ring_color Card ring color.
+ * @param props.prog_bar_bg_color Progress bar background color.
  * @param props.theme Card theme.
  * @returns Card colors.
  */
@@ -136,21 +168,14 @@ const getCardColors = ({
   bg_color,
   border_color,
   ring_color,
+  prog_bar_bg_color,
   theme,
-}: {
-  title_color?: string | undefined;
-  text_color?: string | undefined;
-  icon_color?: string | undefined;
-  bg_color?: string | undefined;
-  border_color?: string | undefined;
-  ring_color?: string | undefined;
-  theme?: string | undefined;
-}): CardColors => {
+}: ColorInput): CardColors => {
   const defaultTheme = themes.default;
   const isThemeProvided = theme !== undefined && theme in themes;
 
   const selectedTheme = isThemeProvided
-    ? themes[theme as keyof typeof themes]
+    ? themes[theme as ThemeName]
     : defaultTheme;
 
   const defaultBorderColor =
@@ -167,8 +192,6 @@ const getCardColors = ({
 
   // get the color provided by the user else the theme color
   // finally if both colors are invalid we use the titleColor
-  // NOTE: no built-in theme defines `ring_color`, so it falls back to the title color.
-  const ringColor = fallbackColor(ring_color, titleColor);
   const iconColor = fallbackColor(
     icon_color || selectedTheme.icon_color,
     "#" + defaultTheme.icon_color,
@@ -186,11 +209,16 @@ const getCardColors = ({
     border_color || defaultBorderColor,
     "#" + defaultBorderColor,
   );
+  // No theme defines `ring_color`, so it falls back to the title color.
+  const ringColor = fallbackColor(ring_color, titleColor);
+  // No theme defines `prog_bar_bg_color`, so it falls back to "#ddd".
+  const progBarBgColor = fallbackColor(prog_bar_bg_color, "#ddd");
 
   if (
     typeof titleColor !== "string" ||
     typeof textColor !== "string" ||
     typeof ringColor !== "string" ||
+    typeof progBarBgColor !== "string" ||
     typeof iconColor !== "string" ||
     typeof borderColor !== "string"
   ) {
@@ -199,14 +227,135 @@ const getCardColors = ({
     );
   }
 
-  return { titleColor, iconColor, textColor, bgColor, borderColor, ringColor };
+  return {
+    titleColor,
+    iconColor,
+    textColor,
+    bgColor,
+    borderColor,
+    ringColor,
+    progBarBgColor,
+  };
 };
 
+type LightDarkColorParams = Partial<
+  Record<`${BaseColorKey}_${ThemeVariant}`, string | undefined>
+>;
+
+/**
+ * Returns the light- or dark-mode-specific color params, given a set of
+ * raw query params. Also removes the "_light" or "_dark" suffixes.
+ *
+ * @param params Raw query params with optional `_light` / `_dark` suffixes.
+ * @param suffix `"_light"` or `"_dark"`.
+ * @returns ColorInput with the suffix stripped, ready for `getCardColors`.
+ */
+const extractLightDarkColors = (
+  params: LightDarkColorParams,
+  suffix: `_${ThemeVariant}`,
+): ColorInput =>
+  Object.fromEntries(
+    BASE_COLOR_KEYS.map((key) => [key, params[`${key}${suffix}`]]),
+  );
+
+/**
+ * Returns resolved colors for both light and dark mode given all input params.
+ *
+ * Each mode resolves independently, then runs the normal `getCardColors` precedence
+ * (explicit color -> theme color -> default theme):
+ *   light: `theme_light ?? theme`, with `*_light` params overriding general ones
+ *   dark:  `theme_dark  ?? theme`, with `*_dark`  params overriding general ones
+ *
+ * Anything a mode does not override falls back to the general params,
+ * so a partial override such as `bg_color_dark` alone keeps every other color from the base theme.
+ *
+ * When no `_light` / `_dark` param is provided at all, `darkColors` is `null` and the caller emits no dark-mode block.
+ *
+ * @param params Raw query params, containing both general and `_light`/`_dark` suffixed colors and themes.
+ * @returns `{ lightColors, darkColors }`, resolved colors for both light and dark mode
+ */
+const getLightDarkColors = (
+  params: ColorInput & LightDarkColorParams,
+): { lightColors: CardColors; darkColors: CardColors | null } => {
+  const lightOverrides = extractLightDarkColors(params, "_light");
+  const darkOverrides = extractLightDarkColors(params, "_dark");
+
+  const hasModeOverrides =
+    Object.values(lightOverrides).some((v) => v !== undefined) ||
+    Object.values(darkOverrides).some((v) => v !== undefined);
+
+  if (!hasModeOverrides) {
+    return { lightColors: getCardColors(params), darkColors: null };
+  }
+
+  const defined = (obj: ColorInput): ColorInput =>
+    Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+
+  return {
+    lightColors: getCardColors({ ...params, ...defined(lightOverrides) }),
+    darkColors: getCardColors({ ...params, ...defined(darkOverrides) }),
+  };
+};
+
+type ColorParams = ColorInput & LightDarkColorParams;
+
+const COLOR_PARAM_KEYS: ReadonlyArray<keyof ColorParams> = [
+  ...BASE_COLOR_KEYS,
+  ...THEME_VARIANTS.flatMap((variant) =>
+    BASE_COLOR_KEYS.map((key) => `${key}_${variant}` as const),
+  ),
+];
+
+/**
+ * Picks all color-related parameters from a query object.
+ *
+ * @param query Raw query parameters.
+ * @returns All color-related parameters.
+ */
+const pickColorParams = (
+  query: Record<string, string | undefined>,
+): ColorParams =>
+  Object.fromEntries(
+    COLOR_PARAM_KEYS.filter((k) => k in query).map((k) => [k, query[k]]),
+  );
+
+/** Params naming a theme rather than holding a color value. */
+const THEME_PARAM_KEYS: ReadonlyArray<keyof ColorParams> = [
+  "theme",
+  ...THEME_VARIANTS.map((variant) => `theme_${variant}` as const),
+];
+
+/**
+ * Finds the first color param holding an invalid color.
+ *
+ * Theme params are skipped: they name a theme, and an unknown name falls back
+ * to the default rather than being an error.
+ *
+ * @param params Color params, as returned by {@link pickColorParams}.
+ * @returns The first invalid param name, or null if all are valid.
+ */
+const findInvalidColorParam = (params: ColorParams): string | null =>
+  findInvalidColor(
+    Object.fromEntries(
+      Object.entries(params).filter(
+        ([key]) => !THEME_PARAM_KEYS.includes(key as keyof ColorParams),
+      ),
+    ),
+  );
+
 export {
-  fallbackColor,
   getCardColors,
+  getLightDarkColors,
   findInvalidColor,
+  findInvalidColorParam,
+  pickColorParams,
   isValidGradient,
   isBareHexColor,
   isPrefixedHexColor,
+
+  // Not re-exported from the package index: internal,
+  // exposed so tests can pin the accepted param list.
+  BASE_COLOR_KEYS,
+  THEME_VARIANTS,
+  COLOR_PARAM_KEYS,
 };

package/src/common/config.ts

@@ -9,7 +9,8 @@ interface Config {
   whitelist: Array<string> | undefined;
   gistWhitelist: Array<string> | undefined;
   excludeRepositories: Array<string>;
-  fetchMultiPageStars: string | undefined;
+  /** Max pages of starred repos to fetch; `Infinity` means every page, `1` only the first. */
+  fetchMultiPageStars: number;
   pats: Array<PersonalAccessToken>;
 }
 
@@ -17,11 +18,19 @@ interface Config {
  * @param value Comma-separated string.
  * @returns Parsed string values.
  */
-const parseCsv = (value: string | undefined): Array<string> | undefined => {
-  if (!value) {
-    return undefined;
+const parseCsv = (value: string | undefined): Array<string> | undefined =>
+  value ? value.split(",") : undefined;
+
+/**
+ * @param value Raw `FETCH_MULTI_PAGE_STARS` value.
+ * @returns Page limit: `"true"` means every page, a positive number caps the pages, anything else means one.
+ */
+const parseFetchMultiPageStars = (value: string | undefined): number => {
+  if (value === "true") {
+    return Infinity;
   }
-  return value.split(",");
+  const limit = Number(value);
+  return limit > 0 ? limit : 1;
 };
 
 /**
@@ -45,37 +54,21 @@ const getDefaultEnv = (): Env => {
   return processEnv ?? {};
 };
 
-/**
- * @param config (Partial) config values to normalize.
- * @returns Normalized config object with defaults applied.
- */
-const normalizeConfig = (config: Partial<Config> = {}): Config => {
-  return {
-    whitelist: config.whitelist,
-    gistWhitelist: config.gistWhitelist,
-    excludeRepositories: config.excludeRepositories ?? [],
-    fetchMultiPageStars: config.fetchMultiPageStars,
-    pats: config.pats ?? [],
-  };
-};
-
 let currentConfig: Config;
 
 /**
  * @param env Environment variables used to build the runtime config.
  */
 export const loadConfigFromEnv = (env: Env = getDefaultEnv()): void => {
-  const whitelist = parseCsv(env["WHITELIST"]);
-  const gistWhitelist = parseCsv(env["GIST_WHITELIST"]);
-  const excludeRepositories = parseCsv(env["EXCLUDE_REPO"]) ?? [];
-
-  currentConfig = normalizeConfig({
-    whitelist,
-    gistWhitelist,
-    excludeRepositories,
-    fetchMultiPageStars: env["FETCH_MULTI_PAGE_STARS"],
+  currentConfig = {
+    whitelist: parseCsv(env["WHITELIST"]),
+    gistWhitelist: parseCsv(env["GIST_WHITELIST"]),
+    excludeRepositories: parseCsv(env["EXCLUDE_REPO"]) ?? [],
+    fetchMultiPageStars: parseFetchMultiPageStars(
+      env["FETCH_MULTI_PAGE_STARS"],
+    ),
     pats: parsePATsFromEnv(env),
-  });
+  };
 };
 
 loadConfigFromEnv();

package/src/common/constants.ts

@@ -1,7 +1,9 @@
+import type { RepositoryAffiliation } from "../graphql/generated/common.js";
+
 /**
  * Valid owner affiliations for GitHub API queries.
  */
-const OWNER_AFFILIATIONS: Array<string> = [
+const OWNER_AFFILIATIONS: Array<RepositoryAffiliation> = [
   "OWNER",
   "COLLABORATOR",
   "ORGANIZATION_MEMBER",

package/src/common/date.ts

@@ -0,0 +1,45 @@
+/** A span between two dates, as GitHub's range arguments take it. */
+interface GitHubDateRange {
+  /** Start of the range, inclusive. */
+  from: Date;
+  /** End of the range, inclusive. */
+  to: Date;
+}
+
+/**
+ * Format a date as a GitHub `DateTime` scalar.
+ * Seconds precision, no milliseconds.
+ *
+ * @param date Date to format.
+ * @returns e.g. `2024-01-01T00:00:00Z`.
+ */
+const toGitHubDateTime = (date: Date): string =>
+  `${date.toISOString().slice(0, 19)}Z`;
+
+/**
+ * The full UTC span of a calendar year, both ends inclusive.
+ *
+ * The end matters to callers that would otherwise leave a range open:
+ * GitHub's `contributionsCollection` defaults `to` to one year after `from`,
+ * which pulls the next 1st of January into the year.
+ *
+ * @param year Four-digit year.
+ * @returns The range covering it.
+ */
+const getGitHubYearRange = (year: number): GitHubDateRange => ({
+  from: new Date(Date.UTC(year, 0, 1)),
+  to: new Date(Date.UTC(year, 11, 31, 23, 59, 59)),
+});
+
+/**
+ * Get diff in minutes between two dates.
+ *
+ * @param d1 First date.
+ * @param d2 Second date.
+ * @returns Number of minutes between the two dates.
+ */
+const dateDiff = (d1: Date, d2: Date): number =>
+  Math.round((d1.getTime() - d2.getTime()) / (1000 * 60));
+
+export { dateDiff, getGitHubYearRange, toGitHubDateTime };
+export type { GitHubDateRange };