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

package/build/common/Card.js

@@ -1,3 +1,4 @@
+import { getCardColors, isPrefixedHexColor, isValidGradient } from "./color.js";
 import { encodeHTML } from "./html.js";
 import { flexLayout } from "./render.js";
 class Card {
@@ -9,6 +10,7 @@ class Card {
     colors;
     title;
     css;
+    darkCss;
     paddingX;
     paddingY;
     titlePrefixIcon;
@@ -18,25 +20,29 @@ 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 = {}, customTitle, defaultTitle = "", titlePrefixIcon, }) {
+    constructor({ width = 100, height = 100, border_radius = 4.5, colors = { light: getCardColors({}), dark: null }, customTitle, defaultTitle = "", titlePrefixIcon, }) {
         this.width = width;
         this.height = height;
         this.hideBorder = false;
         this.hideTitle = false;
-        this.border_radius = border_radius;
-        // returns theme based colors with proper overrides and defaults
+        this.border_radius = parseFloat(String(border_radius));
         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;
         this.titlePrefixIcon = titlePrefixIcon;
@@ -57,10 +63,17 @@ class Card {
         this.a11yDesc = desc;
     }
     /**
-     * @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) {
-        this.css = value;
+    setCSS({ light, dark }) {
+        this.css = light;
+        this.darkCss = dark ?? "";
     }
     /**
      * @param value Whether to hide the border or not.
@@ -72,10 +85,13 @@ class Card {
      * @param value Whether to hide the title or not.
      */
     setHideTitle(value) {
-        this.hideTitle = value;
-        if (value) {
+        if (value && !this.hideTitle) {
             this.height -= 30;
         }
+        if (!value && this.hideTitle) {
+            this.height += 30;
+        }
+        this.hideTitle = value;
     }
     /**
      * @param text The title to set.
@@ -93,7 +109,7 @@ class Card {
         y="0"
         class="header"
         data-testid="header"
-      >${this.title}</text>
+      >${encodeHTML(this.title)}</text>
     `;
         const prefixIcon = `
       <svg
@@ -124,16 +140,12 @@ class Card {
      * @returns The rendered card gradient.
      */
     renderGradient() {
-        if (typeof this.colors.bgColor !== "object") {
-            return "";
-        }
-        const gradients = this.colors.bgColor.slice(1);
-        return typeof this.colors.bgColor === "object"
-            ? `
-        <defs>
+        const buildGradientDef = (id, bgColor) => {
+            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
@@ -142,10 +154,23 @@ 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>
-        `
-            : "";
+        `;
     }
     /**
      * Retrieves css animations for a card.
@@ -174,10 +199,44 @@ 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.
+     */
+    renderDarkMediaBlock() {
+        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) {
+        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}"
@@ -188,12 +247,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) {
@@ -201,6 +260,7 @@ class Card {
             .header { font-size: 15.5px; }
           }
           ${this.css}
+          ${this.renderDarkMediaBlock()}
 
           ${this.getAnimations()}
           ${this.animations
@@ -212,15 +272,16 @@ 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"
+          fill="${typeof this.colors.light.bgColor === "object"
             ? "url(#gradient)"
-            : String(this.colors.bgColor)}"
+            : this.colors.light.bgColor}"
           stroke-opacity="${this.hideBorder ? 0 : 1}"
         />
 

package/build/common/I18n.d.ts

@@ -1,7 +1,9 @@
+/** A map of translation keys to per-locale strings. */
+type TranslationsMap = Record<string, Record<string, string>>;
 /**
  * I18n translation class.
  */
-declare class I18n<Translations extends Record<string, Record<string, string>>> {
+declare class I18n<Translations extends TranslationsMap = TranslationsMap> {
     locale: string;
     translations: Translations;
     /**
@@ -10,7 +12,7 @@ declare class I18n<Translations extends Record<string, Record<string, string>>>
      * @param props.translations Translations.
      */
     constructor({ locale, translations, }: {
-        locale?: string;
+        locale?: string | undefined;
         translations: Translations;
     });
     /**

package/build/common/I18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"I18n.d.ts","sourceRoot":"","sources":["../../src/common/I18n.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,cAAM,IAAI,CAAC,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,CAAC;IAE3B;;;;OAIG;gBACS,EACV,MAAM,EACN,YAAY,GACb,EAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,YAAY,CAAC;KAC5B;IAKD;;;;;OAKG;IACH,CAAC,CAAC,GAAG,EAAE,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM;CAe5C;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"I18n.d.ts","sourceRoot":"","sources":["../../src/common/I18n.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,cAAM,IAAI,CAAC,YAAY,SAAS,eAAe,GAAG,eAAe;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,CAAC;IAE3B;;;;OAIG;gBACS,EACV,MAAM,EACN,YAAY,GACb,EAAE;QAED,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,YAAY,EAAE,YAAY,CAAC;KAC5B;IAKD;;;;;OAKG;IACH,CAAC,CAAC,GAAG,EAAE,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM;CAe5C;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/build/common/color.d.ts

@@ -1,11 +1,37 @@
 /**
- * Retrieves a gradient if color has more than one valid hex codes else a single 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 color The color to parse.
- * @param fallbackColor The fallback color.
- * @returns The gradient or color.
+ * @param value Value to check.
+ * @returns True if the value is a bare hex color.
  */
-declare const fallbackColor: (color: string | undefined, fallbackColor: string | Array<string>) => string | Array<string>;
+declare const isBareHexColor: (value: unknown) => boolean;
+/**
+ * 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 value Value to check.
+ * @returns True if the value is a `#`-prefixed hex color.
+ */
+declare const isPrefixedHexColor: (value: unknown) => boolean;
+/**
+ * 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.
+ */
+declare const isValidGradient: (parts: Array<string>) => boolean;
+/**
+ * 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.
+ */
+declare const findInvalidColor: (colors: Record<string, string | null | undefined>) => string | null;
 /**
  * Object containing card colors.
  */
@@ -16,7 +42,24 @@ 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.
+ */
+declare const BASE_COLOR_KEYS: readonly ["title_color", "icon_color", "text_color", "bg_color", "border_color", "ring_color", "prog_bar_bg_color", "theme"];
+declare const THEME_VARIANTS: readonly ["light", "dark"];
+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.
  *
@@ -27,17 +70,50 @@ 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.
  */
-declare const getCardColors: ({ title_color, text_color, icon_color, bg_color, border_color, ring_color, theme, }: {
-    title_color?: string;
-    text_color?: string;
-    icon_color?: string;
-    bg_color?: string;
-    border_color?: string;
-    ring_color?: string;
-    theme?: string;
-}) => CardColors;
-export { fallbackColor, getCardColors };
+declare const getCardColors: ({ title_color, text_color, icon_color, bg_color, border_color, ring_color, prog_bar_bg_color, theme, }: ColorInput) => CardColors;
+type LightDarkColorParams = Partial<Record<`${BaseColorKey}_${ThemeVariant}`, string | undefined>>;
+/**
+ * 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
+ */
+declare const getLightDarkColors: (params: ColorInput & LightDarkColorParams) => {
+    lightColors: CardColors;
+    darkColors: CardColors | null;
+};
+type ColorParams = ColorInput & LightDarkColorParams;
+declare const COLOR_PARAM_KEYS: ReadonlyArray<keyof ColorParams>;
+/**
+ * Picks all color-related parameters from a query object.
+ *
+ * @param query Raw query parameters.
+ * @returns All color-related parameters.
+ */
+declare const pickColorParams: (query: Record<string, string | undefined>) => ColorParams;
+/**
+ * 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.
+ */
+declare const findInvalidColorParam: (params: ColorParams) => string | null;
+export { getCardColors, getLightDarkColors, findInvalidColor, findInvalidColorParam, pickColorParams, isValidGradient, isBareHexColor, isPrefixedHexColor, BASE_COLOR_KEYS, THEME_VARIANTS, COLOR_PARAM_KEYS, };
 //# sourceMappingURL=color.d.ts.map

package/build/common/color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/common/color.ts"],"names":[],"mappings":"AA2BA;;;;;;GAMG;AACH,QAAA,MAAM,aAAa,GACjB,OAAO,MAAM,GAAG,SAAS,EACzB,eAAe,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KACpC,MAAM,GAAG,KAAK,CAAC,MAAM,CAWvB,CAAC;AAEF;;GAEG;AACH,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,aAAa,GAAI,qFAQpB;IACD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,KAAG,UAuDH,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/common/color.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,QAAA,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,OAExC,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,OAM5C,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,eAAe,GAAI,OAAO,KAAK,CAAC,MAAM,CAAC,KAAG,OAS/C,CAAC;AAeF;;;;;GAKG;AACH,QAAA,MAAM,gBAAgB,GACpB,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,KAChD,MAAM,GAAG,IAOX,CAAC;AAyBF;;GAEG;AACH,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,QAAA,MAAM,eAAe,8HASX,CAAC;AAEX,QAAA,MAAM,cAAc,4BAA6B,CAAC;AAElD,KAAK,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AACrD,KAAK,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpD;;;;GAIG;AACH,KAAK,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,aAAa,GAAI,wGASpB,UAAU,KAAG,UAkEf,CAAC;AAEF,KAAK,oBAAoB,GAAG,OAAO,CACjC,MAAM,CAAC,GAAG,YAAY,IAAI,YAAY,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAC9D,CAAC;AAkBF;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,kBAAkB,GACtB,QAAQ,UAAU,GAAG,oBAAoB,KACxC;IAAE,WAAW,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;CAmB1D,CAAC;AAEF,KAAK,WAAW,GAAG,UAAU,GAAG,oBAAoB,CAAC;AAErD,QAAA,MAAM,gBAAgB,EAAE,aAAa,CAAC,MAAM,WAAW,CAKtD,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,eAAe,GACnB,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACxC,WAGA,CAAC;AAQJ;;;;;;;;GAQG;AACH,QAAA,MAAM,qBAAqB,GAAI,QAAQ,WAAW,KAAG,MAAM,GAAG,IAO3D,CAAC;AAEJ,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,cAAc,EACd,kBAAkB,EAIlB,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,CAAC"}

package/build/common/color.js

@@ -1,22 +1,71 @@
 import { themes } 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) => {
-    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) => {
+    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) => {
-    return (colors.length > 2 &&
-        colors.slice(1).every((color) => isValidHexColor(color)));
+const isPrefixedHexColor = (value) => {
+    return (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) => {
+    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) => {
+    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) => {
+    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.
@@ -30,11 +79,28 @@ const fallbackColor = (color, fallbackColor) => {
     if (colors.length > 1 && isValidGradient(colors)) {
         return colors;
     }
-    if (color !== undefined && isValidHexColor(color)) {
+    if (color !== undefined && isBareHexColor(color)) {
         return `#${color}`;
     }
     return fallbackColor;
 };
+/**
+ * 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",
+];
+const THEME_VARIANTS = ["light", "dark"];
 /**
  * Returns theme based colors with proper overrides and defaults.
  *
@@ -45,10 +111,11 @@ const fallbackColor = (color, fallbackColor) => {
  * @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.
  */
-const getCardColors = ({ title_color, text_color, icon_color, bg_color, border_color, ring_color, theme, }) => {
+const getCardColors = ({ title_color, text_color, icon_color, bg_color, border_color, ring_color, prog_bar_bg_color, theme, }) => {
     const defaultTheme = themes.default;
     const isThemeProvided = theme !== undefined && theme in themes;
     const selectedTheme = isThemeProvided
@@ -62,19 +129,98 @@ const getCardColors = ({ title_color, text_color, icon_color, bg_color, border_c
     const titleColor = fallbackColor(title_color || selectedTheme.title_color, "#" + defaultTheme.title_color);
     // 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);
     const textColor = fallbackColor(text_color || selectedTheme.text_color, "#" + defaultTheme.text_color);
     const bgColor = fallbackColor(bg_color || selectedTheme.bg_color, "#" + defaultTheme.bg_color);
     const borderColor = fallbackColor(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") {
         throw new Error("Unexpected behavior, all colors except background should be string.");
     }
-    return { titleColor, iconColor, textColor, bgColor, borderColor, ringColor };
+    return {
+        titleColor,
+        iconColor,
+        textColor,
+        bgColor,
+        borderColor,
+        ringColor,
+        progBarBgColor,
+    };
 };
-export { fallbackColor, getCardColors };
+/**
+ * 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, suffix) => 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) => {
+    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) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+    return {
+        lightColors: getCardColors({ ...params, ...defined(lightOverrides) }),
+        darkColors: getCardColors({ ...params, ...defined(darkOverrides) }),
+    };
+};
+const COLOR_PARAM_KEYS = [
+    ...BASE_COLOR_KEYS,
+    ...THEME_VARIANTS.flatMap((variant) => BASE_COLOR_KEYS.map((key) => `${key}_${variant}`)),
+];
+/**
+ * Picks all color-related parameters from a query object.
+ *
+ * @param query Raw query parameters.
+ * @returns All color-related parameters.
+ */
+const pickColorParams = (query) => 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 = [
+    "theme",
+    ...THEME_VARIANTS.map((variant) => `theme_${variant}`),
+];
+/**
+ * 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) => findInvalidColor(Object.fromEntries(Object.entries(params).filter(([key]) => !THEME_PARAM_KEYS.includes(key))));
+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, };

package/build/common/config.d.ts

@@ -7,7 +7,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>;
 }
 /**

package/build/common/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AAAA,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,MAAM;IACd,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACzC,mBAAmB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACnC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;CAClC;AAkDD;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAK,GAAqB,KAAG,IAY9D,CAAC;AAIF,eAAO,MAAM,SAAS,QAAO,MAAuB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AAAA,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,MAAM;IACd,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACrC,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACzC,mBAAmB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACnC,4FAA4F;IAC5F,mBAAmB,EAAE,MAAM,CAAC;IAC5B,IAAI,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;CAClC;AA4CD;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAK,GAAqB,KAAG,IAU9D,CAAC;AAIF,eAAO,MAAM,SAAS,QAAO,MAAuB,CAAC"}