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

package/src/common/Card.ts

@@ -1,12 +1,56 @@
-import { getCardColors, isPrefixedHexColor, isValidGradient } from './color.js';
-import type { CardColors } from './color.js';
-import { encodeHTML } from './html.js';
-import { flexLayout } from './render.js';
+import type { Child, CssChild, MarkupElement } from '../markup/index.ts';
+import { atRule, cssComment, el, renderMarkup, rule, style } from '../markup/index.ts';
+
+import { ACCENT, firefoxFontSize, font, TITLE_BAND, TITLE_FIREFOX_SIZE } from './brand.ts';
+import { getCardColors, isPrefixedHexColor, isValidGradient } from './color.ts';
+import type { CardColors } from './color.ts';
+import { flexLayout } from './render.ts';
 
 /**
  * Builds the card CSS for one color scheme from that scheme's resolved colors.
  */
-type CardCSSBuilder = (colors: CardColors) => string;
+type CardCSSBuilder = (colors: CardColors) => Array<CssChild>;
+
+/** Stops every animation, whether the reader asked or the card did. */
+const NO_MOTION = {
+  'animation-duration': '0s !important',
+  'animation-delay': '0s !important',
+} as const;
+
+/**
+ * Retrieves css animations for a card.
+ *
+ * @returns Animation css.
+ */
+const getAnimations = (): Array<CssChild> => [
+  cssComment('Animations'),
+  atRule(
+    '@keyframes scaleInAnimation',
+    rule('from', { transform: 'translate(-5px, 5px) scale(0)' }),
+    rule('to', { transform: 'translate(-5px, 5px) scale(1)' }),
+  ),
+  atRule('@keyframes fadeInAnimation', rule('from', { opacity: 0 }), rule('to', { opacity: 1 })),
+  atRule('@media (prefers-reduced-motion: reduce)', rule('*', NO_MOTION)),
+];
+
+/** One `linearGradient` definition, built from an angle followed by its stops. */
+const buildGradientDef = (id: string, bgColor: Array<string>): MarkupElement => {
+  const gradients = bgColor.slice(1);
+  return el(
+    'linearGradient',
+    {
+      id,
+      gradientTransform: `rotate(${String(bgColor[0])})`,
+      gradientUnits: 'userSpaceOnUse',
+    },
+    gradients.map((grad, index) =>
+      el('stop', {
+        offset: `${(index * 100) / (gradients.length - 1)}%`,
+        'stop-color': `#${grad}`,
+      }),
+    ),
+  );
+};
 
 class Card {
   width: number;
@@ -16,35 +60,22 @@ class Card {
   border_radius: number;
   colors: { light: CardColors; dark: CardColors | null };
   title: string;
-  css: string;
-  darkCss: string;
+  css: Array<CssChild>;
+  darkCss: Array<CssChild>;
   paddingX: number;
   paddingY: number;
-  titlePrefixIcon: string | undefined;
+  titlePrefixIcon: Child;
   animations: boolean;
   a11yTitle: string;
   a11yDesc: string;
 
   /**
    * 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,
+    border_radius = 8,
     colors = { light: getCardColors({}), dark: null },
     customTitle,
     defaultTitle = '',
@@ -57,7 +88,7 @@ class Card {
     colors?: { light: CardColors; dark: CardColors | null };
     customTitle?: string | undefined;
     defaultTitle?: string;
-    titlePrefixIcon?: string;
+    titlePrefixIcon?: Child;
   }) {
     this.width = width;
     this.height = height;
@@ -65,16 +96,16 @@ class Card {
     this.hideBorder = false;
     this.hideTitle = false;
 
-    this.border_radius = parseFloat(String(border_radius));
+    this.border_radius = Number.parseFloat(String(border_radius));
 
     this.colors = colors;
-    this.title = customTitle === undefined ? defaultTitle : customTitle;
+    this.title = customTitle ?? defaultTitle;
 
-    this.css = '';
-    this.darkCss = '';
+    this.css = [];
+    this.darkCss = [];
 
     this.paddingX = 25;
-    this.paddingY = 35;
+    this.paddingY = 30;
     this.titlePrefixIcon = titlePrefixIcon;
     this.animations = true;
     this.a11yTitle = '';
@@ -85,11 +116,6 @@ class Card {
     this.animations = false;
   }
 
-  /**
-   * @param props The props object.
-   * @param props.title Accessibility title.
-   * @param props.desc Accessibility description.
-   */
   setAccessibilityLabel({ title, desc }: { title: string; desc: string }): void {
     this.a11yTitle = title;
     this.a11yDesc = desc;
@@ -101,28 +127,16 @@ class Card {
    * 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 }: { light: CardCSSBuilder; dark: CardCSSBuilder }): void {
     this.css = light(this.colors.light);
-    this.darkCss = this.colors.dark ? dark(this.colors.dark) : '';
+    this.darkCss = this.colors.dark ? dark(this.colors.dark) : [];
   }
 
-  /**
-   * @param value Whether to hide the border or not.
-   */
   setHideBorder(value: boolean): void {
     this.hideBorder = value;
   }
 
-  /**
-   * @param value Whether to hide the title or not.
-   */
   setHideTitle(value: boolean): void {
     if (value && !this.hideTitle) {
       this.height -= 30;
@@ -133,73 +147,75 @@ class Card {
     this.hideTitle = value;
   }
 
-  /**
-   * @param text The title to set.
-   */
   setTitle(text: string): void {
     this.title = text;
   }
 
-  /**
-   * @returns The rendered card title.
-   */
-  renderTitle(): string {
-    const titleText = `
-      <text
-        x="0"
-        y="0"
-        class="header"
-        data-testid="header"
-      >${encodeHTML(this.title)}</text>
-    `;
+  /** @returns The rendered card title. */
+  renderTitle(): MarkupElement {
+    return el(
+      'g',
+      {
+        'data-testid': 'card-title',
+        transform: `translate(${this.paddingX}, ${this.paddingY})`,
+      },
+      flexLayout({
+        items: [
+          this.titlePrefixIcon &&
+            el(
+              'svg',
+              {
+                class: 'title-icon',
+                x: 0,
+                y: -13,
+                viewBox: '0 0 16 16',
+                version: '1.1',
+                width: 16,
+                height: 16,
+              },
+              this.titlePrefixIcon,
+            ),
+          el('text', { x: 0, y: 0, class: 'header', 'data-testid': 'header' }, this.title),
+        ],
+        gap: 25,
+      }),
+      el('rect', {
+        'data-testid': 'title-accent',
+        class: 'title-accent',
+        x: 0,
+        y: ACCENT.y,
+        width: ACCENT.width,
+        height: ACCENT.height,
+        rx: ACCENT.height / 2,
+      }),
+    );
+  }
 
-    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>
-    `;
+  /** Where the body starts, and so where the title band ends. */
+  private get bodyOffset(): number {
+    return this.hideTitle ? this.paddingX : this.paddingY + 25;
   }
 
   /**
-   * @returns The rendered card gradient.
+   * The band behind the title. Its top corners follow the card's own and its bottom
+   * ones stay square, so it meets the body as an edge rather than a floating box.
+   *
+   * @returns The rendered title band.
    */
-  renderGradient(): string {
-    const buildGradientDef = (id: string, bgColor: Array<string>): string => {
-      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>`;
-    };
+  private renderTitleBand(): MarkupElement {
+    const height = this.bodyOffset - TITLE_BAND.gap;
+    const innerWidth = this.width - 1;
+    const r = Math.min(this.border_radius, height, innerWidth / 2);
 
+    return el('path', {
+      'data-testid': 'title-band',
+      class: 'title-band',
+      d: `M0.5 ${0.5 + r}a${r} ${r} 0 0 1 ${r} ${-r}h${innerWidth - 2 * r}a${r} ${r} 0 0 1 ${r} ${r}v${height - r - 0.5}h${-innerWidth}z`,
+    });
+  }
+
+  /** @returns The card's gradient definitions, or nothing when no color is a gradient. */
+  renderGradient(): Child {
     if (
       typeof this.colors.light.bgColor === 'object' &&
       !isValidGradient(this.colors.light.bgColor)
@@ -214,48 +230,24 @@ class Card {
       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>
-        `;
-  }
+    const 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),
+    ].filter(Boolean);
 
-  /**
-   * Retrieves css animations for a card.
-   *
-   * @returns Animation css.
-   */
-  getAnimations = (): string => {
-    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;
-        }
-      }
-    `;
-  };
+    return defs.length === 0 ? undefined : el('defs', {}, defs);
+  }
 
   /**
    * Builds the @media (prefers-color-scheme: dark) CSS block for the card.
-   * Returns an empty string when no dark colors are set.
+   * Returns nothing when no dark colors are set.
    */
-  private renderDarkMediaBlock(): string {
+  private renderDarkMediaBlock(): CssChild {
     if (!this.colors.dark) {
-      return '';
+      return undefined;
     }
 
     const bgFill =
@@ -263,23 +255,21 @@ class Card {
         ? '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}
-          }`;
+    return atRule(
+      '@media (prefers-color-scheme: dark)',
+      rule('.header', { fill: this.colors.dark.titleColor }),
+      rule('.title-icon', { fill: this.colors.dark.iconColor }),
+      rule('.title-accent', { fill: this.colors.dark.iconColor }),
+      rule('.title-band', { fill: this.colors.dark.titleColor }),
+      rule('.card-bg', { fill: bgFill, stroke: this.colors.dark.borderColor }),
+      this.darkCss,
+    );
   }
 
-  /**
-   * The caller must ensure that the passed `body` string is properly sanitized!
-   *
-   * @param body The sanitized inner body of the card.
-   * @returns The rendered card.
-   */
-  render(body: string): string {
+  /** @returns The rendered card. */
+  render(body: Child): string {
     if (!Number.isFinite(this.border_radius)) {
-      throw new Error(`Invalid border radius: "${this.border_radius}"`);
+      throw new TypeError(`Invalid border radius: "${this.border_radius}"`);
     }
     if (!isPrefixedHexColor(this.colors.light.titleColor)) {
       throw new Error(`Invalid title color: "${this.colors.light.titleColor}"`);
@@ -295,70 +285,73 @@ class Card {
       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="${
+    return renderMarkup(
+      el(
+        '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': 'title-id desc-id',
+        },
+        el('title', { id: 'title-id' }, this.a11yTitle),
+        el('desc', { id: 'desc-id' }, this.a11yDesc),
+        style(
+          rule('.header', {
+            font: font('semibold', 'title'),
+            fill: this.colors.light.titleColor,
+            animation: 'fadeInAnimation 0.8s ease-in-out forwards',
+          }),
+          cssComment(
+            'The icon reads against the title rather than with it, so it keeps its own color.',
+          ),
+          rule('.title-icon', {
+            fill: this.colors.light.iconColor,
+            animation: 'fadeInAnimation 0.8s ease-in-out forwards',
+          }),
+          rule('.title-accent', {
+            fill: this.colors.light.iconColor,
+            animation: 'fadeInAnimation 0.8s ease-in-out forwards',
+          }),
+          rule('.title-band', { fill: this.colors.light.titleColor, opacity: TITLE_BAND.opacity }),
+          firefoxFontSize(['.header'], TITLE_FIREFOX_SIZE),
+          this.css,
+          this.renderDarkMediaBlock(),
+          getAnimations(),
+          !this.animations && rule('*', NO_MOTION),
+        ),
+        this.renderGradient(),
+        el('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>
-    `;
+              : this.colors.light.bgColor,
+          'stroke-opacity': this.hideBorder ? 0 : 1,
+        }),
+        !this.hideTitle && this.renderTitleBand(),
+        !this.hideTitle && this.renderTitle(),
+        el(
+          'g',
+          {
+            'data-testid': 'main-card-body',
+            transform: `translate(0, ${this.bodyOffset})`,
+          },
+          body,
+        ),
+      ),
+    );
   }
 }
 
 export { Card };
-export default Card;

package/src/common/I18n.ts

@@ -10,11 +10,6 @@ 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,
@@ -28,18 +23,22 @@ class I18n<Translations extends TranslationsMap = TranslationsMap> {
   }
 
   /**
-   * Get translation.
+   * Get translation, falling back to the English string when the locale has no entry for the key.
    *
-   * @param str String to translate.
    * @returns Translated string.
    */
   t(str: keyof Translations & string): string {
     const translation = this.translations[str];
+    // A key the type says is present can still be missing at runtime: a card passes
+    // a locale table it built, and `i18n.test.ts` covers exactly that.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
     if (!translation) {
       throw new Error(`${str} Translation string not found`);
     }
 
-    const localized = translation[this.locale];
+    // A key is written in `en` first and translated afterwards, so a locale the key has
+    // not reached yet reads the English string rather than failing the whole card.
+    const localized = translation[this.locale] ?? translation[FALLBACK_LOCALE];
     if (!localized) {
       throw new Error(`'${str}' translation not found for locale '${this.locale}'`);
     }

package/src/common/brand.ts

@@ -0,0 +1,109 @@
+/**
+ * The visual vocabulary every card draws with: one font stack, one type scale,
+ * one set of widths and the accent rule that marks a card as this tool's.
+ * A card composes from here; it never writes a `font` shorthand or a size of its own.
+ */
+import type { Child, CssChild } from '../markup/index.ts';
+import { atRule, cssComment, rule } from '../markup/index.ts';
+
+import { icons } from './icons.ts';
+
+const FONT_STACK = `'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif`;
+
+/** The type scale, in px. */
+const FONT_SIZE = {
+  display: 22,
+  title: 18,
+  lead: 16,
+  body: 14,
+  meta: 13,
+  small: 12,
+  micro: 11,
+} as const;
+
+/**
+ * The one size off the scale. Firefox is given 15.5px rather than the scale's next step down,
+ * because that half pixel is inherited tuning for long titles and nothing here can test the
+ * wrapping it protects; it lives with the scale so `brand.ts` still owns every size a card draws.
+ */
+const TITLE_FIREFOX_SIZE = 15.5;
+
+/** `regular` labels, `semibold` the values they label, `bold` the rank glyph alone. */
+const FONT_WEIGHT = {
+  regular: 400,
+  semibold: 600,
+  bold: 700,
+} as const;
+
+type FontSize = keyof typeof FONT_SIZE;
+type FontWeight = keyof typeof FONT_WEIGHT;
+
+/** @returns The `font` shorthand for one step of the scale. */
+const font = (weight: FontWeight, size: FontSize): string =>
+  `${String(FONT_WEIGHT[weight])} ${String(FONT_SIZE[size])}px ${FONT_STACK}`;
+
+/**
+ * Firefox lays Segoe UI out wider than the other engines, so text that fits
+ * elsewhere overflows there; each affected selector steps down a size.
+ *
+ * @returns The `@supports` block that detects Firefox and resizes those selectors.
+ */
+const firefoxFontSize = (selectors: Array<string>, size: FontSize | number): CssChild => {
+  const px = typeof size === 'number' ? size : FONT_SIZE[size];
+  return atRule(
+    '@supports(-moz-appearance: auto)',
+    cssComment('Selector detects Firefox'),
+    selectors.map((selector) => rule(selector, { 'font-size': `${String(px)}px` })),
+  );
+};
+
+/**
+ * The widths a card may default to. A card picks the step nearest what its layout
+ * needs, so cards stacked in a README share an edge instead of forming a ragged one.
+ */
+const CARD_WIDTH = {
+  compact: 300,
+  standard: 400,
+  wide: 500,
+} as const;
+
+/** The tinted band behind every card title: the mark a card is recognized by. */
+const TITLE_BAND = {
+  /** Enough to read as a band on every theme, little enough to leave the title legible. */
+  opacity: 0.08,
+  /** Clear air the band leaves between its foot and the first row of the body. */
+  gap: 9,
+} as const;
+
+/** The rule under the title icon, sitting inside the band. */
+const ACCENT = {
+  width: 32,
+  height: 2,
+  /** Below the title's descenders, clear of the band's foot. */
+  y: 8,
+} as const;
+
+/**
+ * The title icon each card wears. They are distinct on purpose: with the band
+ * and the shared type, the icon is what tells one card from another at a glance.
+ */
+const CARD_ICON = {
+  contributedTo: icons.prs_merged,
+  gist: icons.gist,
+  repo: icons.repo,
+  stats: icons.pulse,
+  topLanguages: icons.code,
+  wakatime: icons.clock,
+} satisfies Record<string, Child>;
+
+export {
+  ACCENT,
+  CARD_ICON,
+  CARD_WIDTH,
+  FONT_SIZE,
+  FONT_WEIGHT,
+  firefoxFontSize,
+  font,
+  TITLE_BAND,
+  TITLE_FIREFOX_SIZE,
+};