@stats-forge/github-stats-forge-core 0.0.2 → 0.2.0

package/build/common/color.d.ts

@@ -3,7 +3,6 @@
  * (`"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;
@@ -12,7 +11,6 @@ declare const isBareHexColor: (value: unknown) => boolean;
  * 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;
@@ -21,14 +19,12 @@ declare const isPrefixedHexColor: (value: unknown) => boolean;
  * 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;
@@ -57,8 +53,8 @@ interface CardColors {
  * 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"];
+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];
 /**
@@ -70,15 +66,6 @@ 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;
@@ -94,9 +81,9 @@ type LightDarkColorParams = Partial<Record<`${BaseColorKey}_${ThemeVariant}`, st
  * 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.
+ * 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) => {

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

@@ -1 +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"}
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/common/color.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,QAAA,MAAM,cAAc,UAAW,OAAO,KAAG,OACW,CAAC;AAErD;;;;;;GAMG;AACH,QAAA,MAAM,kBAAkB,UAAW,OAAO,KAAG,OACyC,CAAC;AAEvF;;;;;;GAMG;AACH,QAAA,MAAM,eAAe,UAAW,KAAK,CAAC,MAAM,CAAC,KAAG,OAS/C,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,iBAAiB,UAAW,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,OAK7D,CAAC;AA8DF;;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,YACnB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,OAAO,CACC,CAAC;AAEX,QAAA,MAAM,cAAc,YAAI,OAAO,EAAE,MAAM,CAAU,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;;;;GAIG;AACH,QAAA,MAAM,aAAa,2GAShB,UAAU,KAAG,UA+Cf,CAAC;AAEF,KAAK,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,YAAY,IAAI,YAAY,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AA8BnG;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,kBAAkB,WACd,UAAU,GAAG,oBAAoB,KACxC;IAAE,WAAW,EAAE,UAAU,CAAC;IAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;CAU1D,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

@@ -1,34 +1,27 @@
 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})$/;
+const HEX_COLOR = /^(?<digits>[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);
-};
+const isBareHexColor = (value) => 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));
-};
+const isPrefixedHexColor = (value) => 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) => {
@@ -37,12 +30,11 @@ const isValidGradient = (parts) => {
         angle !== undefined &&
         angle.trim() !== '' &&
         Number.isFinite(Number(angle)) &&
-        stops.every(isBareHexColor));
+        stops.every((stop) => isBareHexColor(stop)));
 };
 /**
  * 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) => {
@@ -54,11 +46,9 @@ const isValidColorInput = (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 fallbackColor = (color, fallback) => {
     const colors = color ? color.split(',') : [];
     if (colors.length > 1 && isValidGradient(colors)) {
         return colors;
@@ -66,7 +56,39 @@ const fallbackColor = (color, fallbackColor) => {
     if (color !== undefined && isBareHexColor(color)) {
         return `#${color}`;
     }
-    return fallbackColor;
+    return fallback;
+};
+/** Border a light background gets when neither the user nor the theme names one. */
+const LIGHT_BG_BORDER = '#0000001f';
+/** Border a dark background gets when neither the user nor the theme names one. */
+const DARK_BG_BORDER = '#ffffff26';
+/** Border a see-through background gets: neutral, since the page behind it decides the contrast. */
+const TRANSLUCENT_BG_BORDER = '#8b949e59';
+/**
+ * @returns Its `[r, g, b, a]` channels, each on 0–1.
+ */
+const hexChannels = (hex) => {
+    const digits = hex.slice(1);
+    const expanded = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join('') : digits;
+    const channel = (index) => Number.parseInt(expanded.slice(index * 2, index * 2 + 2), 16) / 255;
+    return [channel(0), channel(1), channel(2), expanded.length === 8 ? channel(3) : 1];
+};
+/**
+ * Derives a border from the background, so a dark card never gets a light hairline.
+ *
+ * @returns A translucent `#`-prefixed hex border color.
+ */
+const borderColorFor = (bgColor) => {
+    // A gradient is judged by its first stop.
+    const hex = typeof bgColor === 'string' ? bgColor : `#${bgColor[1] ?? ''}`;
+    if (!isPrefixedHexColor(hex)) {
+        return LIGHT_BG_BORDER;
+    }
+    const [r, g, b, a] = hexChannels(hex);
+    if (a < 0.5) {
+        return TRANSLUCENT_BG_BORDER;
+    }
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5 ? DARK_BG_BORDER : LIGHT_BG_BORDER;
 };
 /**
  * Every color param a card accepts, before any `_light` / `_dark` suffix.
@@ -88,30 +110,18 @@ 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);
+    const themeBorderColor = 'border_color' in selectedTheme ? selectedTheme.border_color : undefined;
+    // Each color is the user's, else the selected theme's, else the default theme's.
+    const titleColor = fallbackColor(title_color || selectedTheme.title_color, `#${defaultTheme.title_color}`);
+    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 || themeBorderColor, borderColorFor(bgColor));
     // 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".
@@ -122,7 +132,7 @@ const getCardColors = ({ title_color, text_color, icon_color, bg_color, border_c
         typeof progBarBgColor !== 'string' ||
         typeof iconColor !== 'string' ||
         typeof borderColor !== 'string') {
-        throw new Error('Unexpected behavior, all colors except background should be string.');
+        throw new TypeError('Unexpected behavior, all colors except background should be string.');
     }
     return {
         titleColor,
@@ -138,11 +148,23 @@ const getCardColors = ({ title_color, text_color, icon_color, bg_color, border_c
  * 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}`]]));
+const extractLightDarkColors = (params, suffix) => {
+    const colors = {};
+    for (const key of BASE_COLOR_KEYS) {
+        const value = params[`${key}${suffix}`];
+        if (value !== undefined) {
+            colors[key] = value;
+        }
+    }
+    return colors;
+};
+/**
+ * Every suffixed key, so asking "any per-scheme colors at all?" is one pass over names,
+ * not two objects built to be thrown away.
+ */
+const MODE_OVERRIDE_KEYS = THEME_VARIANTS.flatMap((variant) => BASE_COLOR_KEYS.map((key) => `${key}_${variant}`));
 /**
  * Returns resolved colors for both light and dark mode given all input params.
  *
@@ -154,23 +176,19 @@ const extractLightDarkColors = (params, suffix) => Object.fromEntries(BASE_COLOR
  * 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.
+ * 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) {
+    // The common case is no per-scheme params at all, so it never builds the overrides.
+    if (!MODE_OVERRIDE_KEYS.some((key) => params[key] !== undefined)) {
         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) }),
+        lightColors: getCardColors({ ...params, ...extractLightDarkColors(params, '_light') }),
+        darkColors: getCardColors({ ...params, ...extractLightDarkColors(params, '_dark') }),
     };
 };
 const COLOR_PARAM_KEYS = [

package/build/common/config.d.ts

@@ -1,4 +1,4 @@
-import type { FetchLike } from './http.js';
+import type { FetchLike } from './http.ts';
 type Env = Record<string, string | undefined>;
 interface PersonalAccessToken {
     /** Env variable the token came from — the retryer logs this name, never the value. */
@@ -32,21 +32,11 @@ export declare class CardConfig {
     /** Transport every fetcher sends through; defaults to `globalThis.fetch`. */
     readonly fetch: FetchLike;
     constructor(init?: CardConfigInit);
-    /**
-     * @param env Environment variables to read — the host passes `process.env` or an equivalent.
-     * @returns Config for this deployment.
-     */
+    /** @returns Config for this deployment. */
     static fromEnv(env: Env): CardConfig;
-    /**
-     * @param id Username or gist id being requested.
-     * @param kind Which allowlist applies.
-     * @returns Whether this deployment serves the id.
-     */
+    /** @returns Whether this deployment serves the id. */
     isAllowed(id: string, kind: 'username' | 'gist'): boolean;
-    /**
-     * @param overrides Fields to replace.
-     * @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request.
-     */
+    /** @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request. */
     with(overrides: CardConfigInit): CardConfig;
 }
 export type { PersonalAccessToken, CardConfigInit };

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,UAAU,mBAAmB;IAC3B,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,mBAAmB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AA8BD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAClD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC9D,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,mFAAmF;IACnF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;gBAEd,IAAI,GAAE,cAAmB;IASrC;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU;IAUpC;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO;IAKzD;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU;CAW5C;AAED,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/common/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,UAAU,mBAAmB;IAC3B,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC1C,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,aAAa,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,mBAAmB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AA2BD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAClD,oEAAoE;IACpE,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC9D,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpD,mFAAmF;IACnF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B,YAAY,IAAI,GAAE,cAAmB,EAOpC;IAED,2CAA2C;IAC3C,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,UAAU,CAQnC;IAED,sDAAsD;IACtD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAGxD;IAED,+FAA+F;IAC/F,IAAI,CAAC,SAAS,EAAE,cAAc,GAAG,UAAU,CAU1C;CACF;AAED,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,CAAC"}

package/build/common/config.js

@@ -1,11 +1,9 @@
 import { defaultFetch } from './http.js';
 /**
- * @param value Comma-separated string.
  * @returns Parsed string values.
  */
 const parseCsv = (value) => 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) => {
@@ -16,7 +14,6 @@ const parseFetchMultiPageStars = (value) => {
     return limit > 0 ? limit : 1;
 };
 /**
- * @param env Environment variables to inspect.
  * @returns Personal access tokens found in the environment.
  */
 const parsePATsFromEnv = (env) => Object.keys(env)
@@ -47,10 +44,7 @@ export class CardConfig {
         this.fetchMultiPageStars = init.fetchMultiPageStars ?? 1;
         this.fetch = init.fetch ?? defaultFetch;
     }
-    /**
-     * @param env Environment variables to read — the host passes `process.env` or an equivalent.
-     * @returns Config for this deployment.
-     */
+    /** @returns Config for this deployment. */
     static fromEnv(env) {
         return new CardConfig({
             pats: parsePATsFromEnv(env),
@@ -60,19 +54,12 @@ export class CardConfig {
             fetchMultiPageStars: parseFetchMultiPageStars(env['FETCH_MULTI_PAGE_STARS']),
         });
     }
-    /**
-     * @param id Username or gist id being requested.
-     * @param kind Which allowlist applies.
-     * @returns Whether this deployment serves the id.
-     */
+    /** @returns Whether this deployment serves the id. */
     isAllowed(id, kind) {
         const list = kind === 'gist' ? this.gistAllowlist : this.usernameAllowlist;
         return list === undefined || list.includes(id);
     }
-    /**
-     * @param overrides Fields to replace.
-     * @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request.
-     */
+    /** @returns A copy with `overrides` applied — how a host swaps in a user's PAT per request. */
     with(overrides) {
         return new CardConfig({
             pats: this.pats,

package/build/common/constants.d.ts

@@ -1,7 +1,11 @@
-import type { RepositoryAffiliation } from '../graphql/generated/common.js';
+import type { RepositoryAffiliation } from '../graphql/generated/common.ts';
+/** The year GitHub launched, and so the earliest one a card can be asked to count from. */
+declare const GITHUB_EPOCH_YEAR = 2008;
+/** A GitHub login: alphanumerics and single inner hyphens, 39 characters at most. */
+declare const GITHUB_USERNAME_PATTERN: RegExp;
 /**
  * Valid owner affiliations for GitHub API queries.
  */
 declare const OWNER_AFFILIATIONS: Array<RepositoryAffiliation>;
-export { OWNER_AFFILIATIONS };
+export { GITHUB_EPOCH_YEAR, GITHUB_USERNAME_PATTERN, OWNER_AFFILIATIONS };
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E;;GAEG;AACH,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,qBAAqB,CAIpD,CAAC;AAEF,OAAO,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E,2FAA2F;AAC3F,QAAA,MAAM,iBAAiB,OAAO,CAAC;AAE/B,qFAAqF;AACrF,QAAA,MAAM,uBAAuB,QAA6C,CAAC;AAE3E;;GAEG;AACH,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,qBAAqB,CAIpD,CAAC;AAEF,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,CAAC"}

package/build/common/constants.js

@@ -1,3 +1,7 @@
+/** The year GitHub launched, and so the earliest one a card can be asked to count from. */
+const GITHUB_EPOCH_YEAR = 2008;
+/** A GitHub login: alphanumerics and single inner hyphens, 39 characters at most. */
+const GITHUB_USERNAME_PATTERN = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i;
 /**
  * Valid owner affiliations for GitHub API queries.
  */
@@ -6,4 +10,4 @@ const OWNER_AFFILIATIONS = [
     'COLLABORATOR',
     'ORGANIZATION_MEMBER',
 ];
-export { OWNER_AFFILIATIONS };
+export { GITHUB_EPOCH_YEAR, GITHUB_USERNAME_PATTERN, OWNER_AFFILIATIONS };

package/build/common/date.d.ts

@@ -1,4 +1,5 @@
-/** A span between two dates, as GitHub's range arguments take it. */
+/** @file A range reaches GitHub one calendar year at a time; `contributionsCollection` refuses a longer one. */
+/** A range between two dates, as GitHub's range arguments take it. */
 interface GitHubDateRange {
     /** Start of the range, inclusive. */
     from: Date;
@@ -9,21 +10,65 @@ interface GitHubDateRange {
  * 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`.
  */
 declare const toGitHubDateTime: (date: Date) => string;
 /**
- * The full UTC span of a calendar year, both ends inclusive.
+ * The full UTC range 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.
  */
 declare const getGitHubYearRange: (year: number) => GitHubDateRange;
-export { getGitHubYearRange, toGitHubDateTime };
+/**
+ * The widest range a card can be asked for: GitHub's first year through the end of this one.
+ * The far end is the end of the year, not today, because a bare `to=2026` widens to its 31st of December.
+ *
+ * @returns The range, in UTC.
+ */
+declare const getWidestRange: () => GitHubDateRange;
+/**
+ * The range a card counts within, from the ends the query named.
+ *
+ * @returns The range, each open end filled from {@link getWidestRange}.
+ */
+declare const toRange: (from: Date | undefined, to: Date | undefined) => GitHubDateRange;
+/**
+ * Read one end of a range, written as `2024`, `2024-03` or `2024-03-15`.
+ * A partial date covers the whole of what it names, so `2024` starts on the 1st of January
+ * and ends on the 31st of December.
+ *
+ * @returns The instant, or `undefined` when the text does not name a date that exists.
+ */
+declare const parseRangeDate: (value: string, end: 'from' | 'to') => Date | undefined;
+/**
+ * Split a range into one per calendar year, each clipped to it.
+ *
+ * @returns Them, oldest first; empty when the range is inverted.
+ */
+declare const toYearRanges: ({ from, to }: GitHubDateRange) => Array<GitHubDateRange>;
+/**
+ * Whole years as a card writes them.
+ *
+ * @returns e.g. `2024` or `2020–2024`.
+ */
+declare const formatYears: (first: number, last: number) => string;
+/**
+ * A range as a card writes it, at the coarsest granularity that stays true.
+ *
+ * @returns e.g. `2024`, `2020–2024` or `2024-03-15 – 2024-06-30`.
+ */
+declare const formatRange: ({ from, to }: GitHubDateRange) => string;
+/**
+ * The ranges a walk asks GitHub for: one per calendar year the account contributed in.
+ * Ordered here, which is what makes a walk's ties chronological.
+ *
+ * @returns Them, oldest first.
+ */
+declare const toContributionRanges: (contributionYears: ReadonlyArray<number>, range: GitHubDateRange) => Array<GitHubDateRange>;
+export { formatRange, formatYears, getWidestRange, getGitHubYearRange, parseRangeDate, toContributionRanges, toGitHubDateTime, toRange, toYearRanges, };
 export type { GitHubDateRange };
 //# sourceMappingURL=date.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/common/date.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,UAAU,eAAe;IACvB,qCAAqC;IACrC,IAAI,EAAE,IAAI,CAAC;IACX,mCAAmC;IACnC,EAAE,EAAE,IAAI,CAAC;CACV;AAED;;;;;;GAMG;AACH,QAAA,MAAM,gBAAgB,GAAI,MAAM,IAAI,KAAG,MAA+C,CAAC;AAEvF;;;;;;;;;GASG;AACH,QAAA,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,eAGzC,CAAC;AAEH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/common/date.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAIhH,sEAAsE;AACtE,UAAU,eAAe;IACvB,qCAAqC;IACrC,IAAI,EAAE,IAAI,CAAC;IACX,mCAAmC;IACnC,EAAE,EAAE,IAAI,CAAC;CACV;AAKD;;;;;GAKG;AACH,QAAA,MAAM,gBAAgB,SAAU,IAAI,KAAG,MAA+C,CAAC;AAEvF;;;;;;;;GAQG;AACH,QAAA,MAAM,kBAAkB,SAAU,MAAM,KAAG,eAGzC,CAAC;AAEH;;;;;GAKG;AACH,QAAA,MAAM,cAAc,QAAO,eAGzB,CAAC;AAEH;;;;GAIG;AACH,QAAA,MAAM,OAAO,SAAU,IAAI,GAAG,SAAS,MAAM,IAAI,GAAG,SAAS,KAAG,eAG/D,CAAC;AAEF;;;;;;GAMG;AACH,QAAA,MAAM,cAAc,UAAW,MAAM,OAAO,MAAM,GAAG,IAAI,KAAG,IAAI,GAAG,SA2BlE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,YAAY,iBAAkB,eAAe,KAAG,KAAK,CAAC,eAAe,CAW1E,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,WAAW,UAAW,MAAM,QAAQ,MAAM,KAAG,MACD,CAAC;AAEnD;;;;GAIG;AACH,QAAA,MAAM,WAAW,iBAAkB,eAAe,KAAG,MAWpD,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,oBAAoB,sBACL,aAAa,CAAC,MAAM,CAAC,SACjC,eAAe,KACrB,KAAK,CAAC,eAAe,CAGvB,CAAC;AAEF,OAAO,EACL,WAAW,EACX,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,OAAO,EACP,YAAY,GACb,CAAC;AACF,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/build/common/date.js

@@ -1,23 +1,123 @@
+/** @file A range reaches GitHub one calendar year at a time; `contributionsCollection` refuses a longer one. */
+import { GITHUB_EPOCH_YEAR } from './constants.js';
+/** A year, a year and month, or a full date. */
+const RANGE_DATE_PATTERN = /^(?<year>\d{4})(?:-(?<month>\d{2})(?:-(?<day>\d{2}))?)?$/;
 /**
  * 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.toISOString().slice(0, 19)}Z`;
 /**
- * The full UTC span of a calendar year, both ends inclusive.
+ * The full UTC range 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) => ({
     from: new Date(Date.UTC(year, 0, 1)),
     to: new Date(Date.UTC(year, 11, 31, 23, 59, 59)),
 });
-export { getGitHubYearRange, toGitHubDateTime };
+/**
+ * The widest range a card can be asked for: GitHub's first year through the end of this one.
+ * The far end is the end of the year, not today, because a bare `to=2026` widens to its 31st of December.
+ *
+ * @returns The range, in UTC.
+ */
+const getWidestRange = () => ({
+    from: getGitHubYearRange(GITHUB_EPOCH_YEAR).from,
+    to: getGitHubYearRange(new Date().getUTCFullYear()).to,
+});
+/**
+ * The range a card counts within, from the ends the query named.
+ *
+ * @returns The range, each open end filled from {@link getWidestRange}.
+ */
+const toRange = (from, to) => {
+    const widest = getWidestRange();
+    return { from: from ?? widest.from, to: to ?? widest.to };
+};
+/**
+ * Read one end of a range, written as `2024`, `2024-03` or `2024-03-15`.
+ * A partial date covers the whole of what it names, so `2024` starts on the 1st of January
+ * and ends on the 31st of December.
+ *
+ * @returns The instant, or `undefined` when the text does not name a date that exists.
+ */
+const parseRangeDate = (value, end) => {
+    const match = RANGE_DATE_PATTERN.exec(value);
+    if (!match) {
+        return undefined;
+    }
+    const { year: yearText, month: monthText, day: dayText } = match.groups ?? {};
+    const year = Number(yearText);
+    const month = monthText === undefined ? 1 : Number(monthText);
+    const day = dayText === undefined ? 1 : Number(dayText);
+    const start = new Date(Date.UTC(year, month - 1, day));
+    // Date.UTC rolls an impossible date forward rather than refusing it
+    if (start.getUTCMonth() + 1 !== month || start.getUTCDate() !== day) {
+        return undefined;
+    }
+    if (end === 'from') {
+        return start;
+    }
+    const nextUnit = dayText !== undefined
+        ? Date.UTC(year, month - 1, day + 1)
+        : monthText !== undefined
+            ? Date.UTC(year, month, 1)
+            : Date.UTC(year + 1, 0, 1);
+    return new Date(nextUnit - 1000);
+};
+/**
+ * Split a range into one per calendar year, each clipped to it.
+ *
+ * @returns Them, oldest first; empty when the range is inverted.
+ */
+const toYearRanges = ({ from, to }) => {
+    const ranges = [];
+    for (let year = from.getUTCFullYear(); year <= to.getUTCFullYear(); year += 1) {
+        const yearRange = getGitHubYearRange(year);
+        const start = from > yearRange.from ? from : yearRange.from;
+        const end = to < yearRange.to ? to : yearRange.to;
+        if (start <= end) {
+            ranges.push({ from: start, to: end });
+        }
+    }
+    return ranges;
+};
+/**
+ * Whole years as a card writes them.
+ *
+ * @returns e.g. `2024` or `2020–2024`.
+ */
+const formatYears = (first, last) => first === last ? `${first}` : `${first}–${last}`;
+/**
+ * A range as a card writes it, at the coarsest granularity that stays true.
+ *
+ * @returns e.g. `2024`, `2020–2024` or `2024-03-15 – 2024-06-30`.
+ */
+const formatRange = ({ from, to }) => {
+    const firstYear = from.getUTCFullYear();
+    const lastYear = to.getUTCFullYear();
+    const wholeYears = from.getTime() === getGitHubYearRange(firstYear).from.getTime() &&
+        to.getTime() === getGitHubYearRange(lastYear).to.getTime();
+    if (!wholeYears) {
+        return `${from.toISOString().slice(0, 10)} – ${to.toISOString().slice(0, 10)}`;
+    }
+    return formatYears(firstYear, lastYear);
+};
+/**
+ * The ranges a walk asks GitHub for: one per calendar year the account contributed in.
+ * Ordered here, which is what makes a walk's ties chronological.
+ *
+ * @returns Them, oldest first.
+ */
+const toContributionRanges = (contributionYears, range) => {
+    const contributed = new Set(contributionYears);
+    return toYearRanges(range).filter((year) => contributed.has(year.from.getUTCFullYear()));
+};
+export { formatRange, formatYears, getWidestRange, getGitHubYearRange, parseRangeDate, toContributionRanges, toGitHubDateTime, toRange, toYearRanges, };

package/build/common/emojiMap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolves a GitHub emoji shortcode to its unicode character.
+ *
+ * @returns The emoji, or `undefined` when GitHub has no such shortcode.
+ */
+declare const getEmoji: (name: string) => string | undefined;
+export { getEmoji };
+//# sourceMappingURL=emojiMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emojiMap.d.ts","sourceRoot":"","sources":["../../src/common/emojiMap.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,QAAA,MAAM,QAAQ,SAAU,MAAM,KAAG,MAAM,GAAG,SAA2B,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/build/common/emojiMap.js

@@ -0,0 +1,10 @@
+import emojiMapJson from './emojiMap.json' with { type: 'json' };
+// The generated JSON types has literal keys; index it as a plain lookup table.
+const emojiMap = emojiMapJson;
+/**
+ * Resolves a GitHub emoji shortcode to its unicode character.
+ *
+ * @returns The emoji, or `undefined` when GitHub has no such shortcode.
+ */
+const getEmoji = (name) => emojiMap[name];
+export { getEmoji };