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

package/src/common/Card.ts

@@ -1,17 +1,18 @@
+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 {
@@ -20,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;
@@ -33,29 +35,34 @@ class Card {
   /**
    * Creates a new card instance.
    *
+   * The caller must ensure that the passed `titlePrefixIcon` is properly sanitized!
+   *
    * @param props Card arguments.
    * @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 Card title prefix icon.
+   * @param props.titlePrefixIcon Sanitized card title prefix icon.
    */
   constructor({
     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;
   }) {
@@ -65,15 +72,13 @@ class Card {
     this.hideBorder = false;
     this.hideTitle = false;
 
-    this.border_radius = border_radius;
+    this.border_radius = parseFloat(String(border_radius));
 
-    // returns theme based colors with proper overrides and defaults
     this.colors = colors;
-    this.title = encodeHTML(
-      customTitle === undefined ? defaultTitle : customTitle,
-    );
+    this.title = customTitle === undefined ? defaultTitle : customTitle;
 
     this.css = "";
+    this.darkCss = "";
 
     this.paddingX = 25;
     this.paddingY = 35;
@@ -104,10 +109,17 @@ class Card {
   }
 
   /**
-   * @param value The CSS to add to the card.
+   * Sets the card CSS for light and dark mode.
+   *
+   * 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 ?? "";
   }
 
   /**
@@ -121,10 +133,13 @@ class Card {
    * @param value Whether to hide the title or not.
    */
   setHideTitle(value: boolean): void {
-    this.hideTitle = value;
-    if (value) {
+    if (value && !this.hideTitle) {
       this.height -= 30;
     }
+    if (!value && this.hideTitle) {
+      this.height += 30;
+    }
+    this.hideTitle = value;
   }
 
   /**
@@ -144,7 +159,7 @@ class Card {
         y="0"
         class="header"
         data-testid="header"
-      >${this.title}</text>
+      >${encodeHTML(this.title)}</text>
     `;
 
     const prefixIcon = `
@@ -177,17 +192,12 @@ class Card {
    * @returns The rendered card gradient.
    */
   renderGradient(): string {
-    if (typeof this.colors.bgColor !== "object") {
-      return "";
-    }
-
-    const gradients = this.colors.bgColor.slice(1);
-    return typeof this.colors.bgColor === "object"
-      ? `
-        <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
@@ -196,10 +206,33 @@ 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>
-        `
-      : "";
+        `;
   }
 
   /**
@@ -230,10 +263,55 @@ class Card {
   };
 
   /**
-   * @param body The inner body of the 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!
+   *
+   * @param body The sanitized inner body of the card.
    * @returns The rendered card.
    */
   render(body: string): string {
+    if (!Number.isFinite(this.border_radius)) {
+      throw new Error(`Invalid border radius: "${this.border_radius}"`);
+    }
+    if (!isPrefixedHexColor(this.colors.light.titleColor)) {
+      throw new Error(`Invalid title color: "${this.colors.light.titleColor}"`);
+    }
+    if (!isPrefixedHexColor(this.colors.light.borderColor)) {
+      throw new Error(
+        `Invalid border color: "${this.colors.light.borderColor}"`,
+      );
+    }
+    if (
+      !(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.light.bgColor)}`,
+      );
+    }
+
     return `
       <svg
         width="${this.width}"
@@ -244,12 +322,12 @@ class Card {
         role="img"
         aria-labelledby="descId"
       >
-        <title id="titleId">${this.a11yTitle}</title>
-        <desc id="descId">${this.a11yDesc}</desc>
+        <title id="titleId">${encodeHTML(this.a11yTitle)}</title>
+        <desc id="descId">${encodeHTML(this.a11yDesc)}</desc>
         <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) {
@@ -257,6 +335,7 @@ class Card {
             .header { font-size: 15.5px; }
           }
           ${this.css}
+          ${this.renderDarkMediaBlock()}
 
           ${this.getAnimations()}
           ${
@@ -270,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,30 +1,87 @@
 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 =
+  /^([A-Fa-f0-9]{8}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{3})$/;
 
 /**
- * Checks if a string is a valid hex color.
+ * Checks if a value is a bare hex color, i.e. hex digits with no `#` prefix
+ * (`"f00"`, `"ffffff"`). This is the form user-supplied color params and
+ * gradient stops arrive in.
  *
- * @param hexColor String to check.
- * @returns True if the given string is a valid hex color.
+ * @param value Value to check.
+ * @returns True if the value is a bare hex color.
  */
-const isValidHexColor = (hexColor: string): boolean => {
-  return new RegExp(
-    /^([A-Fa-f0-9]{8}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4})$/,
-  ).test(hexColor);
+const isBareHexColor = (value: unknown): boolean => {
+  return typeof value === "string" && HEX_COLOR.test(value);
 };
 
 /**
- * Check if the given string is a valid gradient.
+ * Checks if a value is a `#`-prefixed hex color (`"#f00"`, `"#ffffff"`). This
+ * is the form colors take once resolved by {@link getCardColors}, i.e. right
+ * before they are written into the SVG.
  *
- * @param colors Array of colors.
- * @returns True if the given string is a valid gradient.
+ * @param value Value to check.
+ * @returns True if the value is a `#`-prefixed hex color.
  */
-const isValidGradient = (colors: Array<string>): boolean => {
+const isPrefixedHexColor = (value: unknown): boolean => {
   return (
-    colors.length > 2 &&
-    colors.slice(1).every((color) => isValidHexColor(color))
+    typeof value === "string" &&
+    value.startsWith("#") &&
+    HEX_COLOR.test(value.slice(1))
   );
 };
 
+/**
+ * Checks if the given parts form a valid gradient: a finite numeric angle
+ * followed by at least two bare-hex color stops, e.g. `["90", "f00", "0f0"]`.
+ * The angle is written into the SVG `gradientTransform="rotate(...)"`.
+ *
+ * @param parts Gradient parts: `[angle, ...stops]`.
+ * @returns True if the parts form a valid gradient.
+ */
+const isValidGradient = (parts: Array<string>): boolean => {
+  const [angle, ...stops] = parts;
+  return (
+    stops.length >= 2 &&
+    angle !== undefined &&
+    angle.trim() !== "" &&
+    Number.isFinite(Number(angle)) &&
+    stops.every(isBareHexColor)
+  );
+};
+
+/**
+ * Checks if a string is a valid input for a color or gradient.
+ *
+ * @param color String to check, may be null or undefined.
+ * @returns True if the given string is a valid input.
+ */
+const isValidColorInput = (color: string | null | undefined): boolean => {
+  if (color === null || color === undefined) {
+    return true;
+  }
+  return isValidGradient(color.split(",")) || isBareHexColor(color);
+};
+
+/**
+ * Iterates over a collection of colors inputs and verifies that each is a valid color or gradient.
+ *
+ * @param colors Object whose values are checked as valid color inputs.
+ * @return The first key where the associated input value is not valid. null if all inputs are valid.
+ */
+const findInvalidColor = (
+  colors: Record<string, string | null | undefined>,
+): string | null => {
+  for (const [key, value] of Object.entries(colors)) {
+    if (!isValidColorInput(value)) {
+      return key;
+    }
+  }
+  return null;
+};
+
 /**
  * Retrieves a gradient if color has more than one valid hex codes else a single color.
  *
@@ -41,7 +98,7 @@ const fallbackColor = (
     return colors;
   }
 
-  if (color !== undefined && isValidHexColor(color)) {
+  if (color !== undefined && isBareHexColor(color)) {
     return `#${color}`;
   }
 
@@ -58,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.
  *
@@ -70,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.
  */
@@ -80,21 +168,14 @@ const getCardColors = ({
   bg_color,
   border_color,
   ring_color,
+  prog_bar_bg_color,
   theme,
-}: {
-  title_color?: string;
-  text_color?: string;
-  icon_color?: string;
-  bg_color?: string;
-  border_color?: string;
-  ring_color?: string;
-  theme?: string;
-}): 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 =
@@ -111,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,
@@ -130,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"
   ) {
@@ -143,7 +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) }),
+  };
 };
 
-export { fallbackColor, getCardColors };
+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 {
+  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,
+};