@stats-forge/github-stats-forge-core 0.0.1

package/build/common/Card.js

@@ -0,0 +1,305 @@
+import { getCardColors, isPrefixedHexColor, isValidGradient } from './color.js';
+import { encodeHTML } from './html.js';
+import { flexLayout } from './render.js';
+class Card {
+    width;
+    height;
+    hideBorder;
+    hideTitle;
+    border_radius;
+    colors;
+    title;
+    css;
+    darkCss;
+    paddingX;
+    paddingY;
+    titlePrefixIcon;
+    animations;
+    a11yTitle;
+    a11yDesc;
+    /**
+     * 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 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.
+     */
+    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 = parseFloat(String(border_radius));
+        this.colors = colors;
+        this.title = customTitle === undefined ? defaultTitle : customTitle;
+        this.css = '';
+        this.darkCss = '';
+        this.paddingX = 25;
+        this.paddingY = 35;
+        this.titlePrefixIcon = titlePrefixIcon;
+        this.animations = true;
+        this.a11yTitle = '';
+        this.a11yDesc = '';
+    }
+    disableAnimations() {
+        this.animations = false;
+    }
+    /**
+     * @param props The props object.
+     * @param props.title Accessibility title.
+     * @param props.desc Accessibility description.
+     */
+    setAccessibilityLabel({ title, desc }) {
+        this.a11yTitle = title;
+        this.a11yDesc = desc;
+    }
+    /**
+     * Sets the card CSS for light and dark mode.
+     *
+     * Each builder receives the colors of its own color scheme,
+     * so a card never handles a missing dark palette itself:
+     * `dark` runs only when the card has dark colors, and always with non-null ones.
+     *
+     * @warning The caller must ensure that the returned CSS strings are properly sanitized!
+     *
+     * @param props The props object.
+     * @param props.light Builds the CSS applied unconditionally (light/default mode).
+     * @param props.dark Builds the CSS placed inside a `@media (prefers-color-scheme: dark)` block.
+     */
+    setCSS({ light, dark }) {
+        this.css = light(this.colors.light);
+        this.darkCss = this.colors.dark ? dark(this.colors.dark) : '';
+    }
+    /**
+     * @param value Whether to hide the border or not.
+     */
+    setHideBorder(value) {
+        this.hideBorder = value;
+    }
+    /**
+     * @param value Whether to hide the title or not.
+     */
+    setHideTitle(value) {
+        if (value && !this.hideTitle) {
+            this.height -= 30;
+        }
+        if (!value && this.hideTitle) {
+            this.height += 30;
+        }
+        this.hideTitle = value;
+    }
+    /**
+     * @param text The title to set.
+     */
+    setTitle(text) {
+        this.title = text;
+    }
+    /**
+     * @returns The rendered card title.
+     */
+    renderTitle() {
+        const titleText = `
+      <text
+        x="0"
+        y="0"
+        class="header"
+        data-testid="header"
+      >${encodeHTML(this.title)}</text>
+    `;
+        const prefixIcon = `
+      <svg
+        class="icon"
+        x="0"
+        y="-13"
+        viewBox="0 0 16 16"
+        version="1.1"
+        width="16"
+        height="16"
+      >
+        ${String(this.titlePrefixIcon)}
+      </svg>
+    `;
+        return `
+      <g
+        data-testid="card-title"
+        transform="translate(${this.paddingX}, ${this.paddingY})"
+      >
+        ${flexLayout({
+            items: [this.titlePrefixIcon ? prefixIcon : '', titleText],
+            gap: 25,
+        }).join('')}
+      </g>
+    `;
+    }
+    /**
+     * @returns The rendered card gradient.
+     */
+    renderGradient() {
+        const buildGradientDef = (id, bgColor) => {
+            const gradients = bgColor.slice(1);
+            return `
+          <linearGradient
+            id="${id}"
+            gradientTransform="rotate(${String(bgColor[0])})"
+            gradientUnits="userSpaceOnUse"
+          >
+            ${gradients
+                .map((grad, index) => {
+                const offset = (index * 100) / (gradients.length - 1);
+                return `<stop offset="${offset}%" stop-color="#${grad}" />`;
+            })
+                .join(',')}
+          </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.
+     *
+     * @returns Animation css.
+     */
+    getAnimations = () => {
+        return `
+      /* Animations */
+      @keyframes scaleInAnimation {
+        from {
+          transform: translate(-5px, 5px) scale(0);
+        }
+        to {
+          transform: translate(-5px, 5px) scale(1);
+        }
+      }
+      @keyframes fadeInAnimation {
+        from {
+          opacity: 0;
+        }
+        to {
+          opacity: 1;
+        }
+      }
+    `;
+    };
+    /**
+     * 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}"
+        height="${this.height}"
+        viewBox="0 0 ${this.width} ${this.height}"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        role="img"
+        aria-labelledby="titleId descId"
+      >
+        <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: ${this.colors.light.titleColor};
+            animation: fadeInAnimation 0.8s ease-in-out forwards;
+          }
+          @supports(-moz-appearance: auto) {
+            /* Selector detects Firefox */
+            .header { font-size: 15.5px; }
+          }
+          ${this.css}
+          ${this.renderDarkMediaBlock()}
+
+          ${this.getAnimations()}
+          ${this.animations
+            ? ''
+            : `* { animation-duration: 0s !important; animation-delay: 0s !important; }`}
+        </style>
+
+        ${this.renderGradient()}
+
+        <rect
+          data-testid="card-bg"
+          class="card-bg"
+          x="0.5"
+          y="0.5"
+          rx="${this.border_radius}"
+          height="99%"
+          stroke="${this.colors.light.borderColor}"
+          width="${this.width - 1}"
+          fill="${typeof this.colors.light.bgColor === 'object'
+            ? 'url(#gradient)'
+            : this.colors.light.bgColor}"
+          stroke-opacity="${this.hideBorder ? 0 : 1}"
+        />
+
+        ${this.hideTitle ? '' : this.renderTitle()}
+
+        <g
+          data-testid="main-card-body"
+          transform="translate(0, ${this.hideTitle ? this.paddingX : this.paddingY + 20})"
+        >
+          ${body}
+        </g>
+      </svg>
+    `;
+    }
+}
+export { Card };
+export default Card;

package/build/common/I18n.d.ts

@@ -0,0 +1,27 @@
+/** A map of translation keys to per-locale strings. */
+type TranslationsMap = Record<string, Record<string, string>>;
+/**
+ * I18n translation class.
+ */
+declare class I18n<Translations extends TranslationsMap = TranslationsMap> {
+    locale: string;
+    translations: Translations;
+    /**
+     * @param props Constructor arguments.
+     * @param props.locale Locale.
+     * @param props.translations Translations.
+     */
+    constructor({ locale, translations, }: {
+        locale?: string | undefined;
+        translations: Translations;
+    });
+    /**
+     * Get translation.
+     *
+     * @param str String to translate.
+     * @returns Translated string.
+     */
+    t(str: keyof Translations & string): string;
+}
+export { I18n };
+//# sourceMappingURL=I18n.d.ts.map

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

@@ -0,0 +1 @@
+{"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;CAa5C;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/build/common/I18n.js

@@ -0,0 +1,35 @@
+const FALLBACK_LOCALE = 'en';
+/**
+ * I18n translation class.
+ */
+class I18n {
+    locale;
+    translations;
+    /**
+     * @param props Constructor arguments.
+     * @param props.locale Locale.
+     * @param props.translations Translations.
+     */
+    constructor({ locale, translations, }) {
+        this.locale = locale || FALLBACK_LOCALE;
+        this.translations = translations;
+    }
+    /**
+     * Get translation.
+     *
+     * @param str String to translate.
+     * @returns Translated string.
+     */
+    t(str) {
+        const translation = this.translations[str];
+        if (!translation) {
+            throw new Error(`${str} Translation string not found`);
+        }
+        const localized = translation[this.locale];
+        if (!localized) {
+            throw new Error(`'${str}' translation not found for locale '${this.locale}'`);
+        }
+        return localized;
+    }
+}
+export { I18n };

package/build/common/color.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 value Value to check.
+ * @returns True if the value is a bare hex color.
+ */
+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;
+/**
+ * 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.
+ */
+declare const isValidColorInput: (color: string | null | undefined) => boolean;
+/**
+ * Resolved card colors for a single color scheme, as written into the SVG.
+ */
+interface CardColors {
+    /** Card title color. */
+    titleColor: string;
+    /** Card icon color. */
+    iconColor: string;
+    /** Card text color. */
+    textColor: string;
+    /** Card background color, or a gradient as `[angle, ...stops]`. */
+    bgColor: string | Array<string>;
+    /** Card border color. */
+    borderColor: string;
+    /** Stats card rank ring color. */
+    ringColor: string;
+    /** Progress bar background color. */
+    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.
+ *
+ * @param props Function arguments.
+ * @param props.title_color Card title color.
+ * @param props.text_color Card text color.
+ * @param props.icon_color Card icon color.
+ * @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, 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>;
+/** Params naming a theme rather than holding a color value. */
+declare const THEME_PARAM_KEYS: ReadonlyArray<keyof ColorParams>;
+export type { CardColors, ColorParams };
+export { isValidColorInput, THEME_PARAM_KEYS, getCardColors, getLightDarkColors, isValidGradient, isBareHexColor, isPrefixedHexColor, BASE_COLOR_KEYS, THEME_VARIANTS, COLOR_PARAM_KEYS, };
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/common/color.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,QAAA,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,OAExC,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,OAE5C,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,eAAe,GAAI,OAAO,KAAK,CAAC,MAAM,CAAC,KAAG,OAS/C,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,iBAAiB,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,OAK7D,CAAC;AAyBF;;GAEG;AACH,UAAU,UAAU;IAClB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,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,UAoDf,CAAC;AAEF,KAAK,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,YAAY,IAAI,YAAY,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAenG;;;;;;;;;;;;;;;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,+DAA+D;AAC/D,QAAA,MAAM,gBAAgB,EAAE,aAAa,CAAC,MAAM,WAAW,CAGtD,CAAC;AAEF,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AAExC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,kBAAkB,EAIlB,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,CAAC"}

package/build/common/color.js

@@ -0,0 +1,188 @@
+import { isThemeName, 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 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 value Value to check.
+ * @returns True if the value is a bare hex color.
+ */
+const isBareHexColor = (value) => {
+    return typeof value === 'string' && HEX_COLOR.test(value);
+};
+/**
+ * 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.
+ */
+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);
+};
+/**
+ * Retrieves a gradient if color has more than one valid hex codes else a single color.
+ *
+ * @param color The color to parse.
+ * @param fallbackColor The fallback color.
+ * @returns The gradient or color.
+ */
+const fallbackColor = (color, fallbackColor) => {
+    const colors = color ? color.split(',') : [];
+    if (colors.length > 1 && isValidGradient(colors)) {
+        return colors;
+    }
+    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.
+ *
+ * @param props Function arguments.
+ * @param props.title_color Card title color.
+ * @param props.text_color Card text color.
+ * @param props.icon_color Card icon color.
+ * @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, prog_bar_bg_color, theme, }) => {
+    const defaultTheme = themes.default;
+    const selectedTheme = isThemeName(theme) ? themes[theme] : defaultTheme;
+    const defaultBorderColor = 'border_color' in selectedTheme ? selectedTheme.border_color : defaultTheme.border_color;
+    // get the color provided by the user else the theme color
+    // finally if both colors are invalid fallback to default theme
+    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
+    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,
+        progBarBgColor,
+    };
+};
+/**
+ * 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}`)),
+];
+/** Params naming a theme rather than holding a color value. */
+const THEME_PARAM_KEYS = [
+    'theme',
+    ...THEME_VARIANTS.map((variant) => `theme_${variant}`),
+];
+export { isValidColorInput, THEME_PARAM_KEYS, getCardColors, getLightDarkColors, 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, };