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

package/src/common/Card.ts

@@ -1,12 +1,55 @@
-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 { 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 +59,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 +87,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,13 +95,13 @@ 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;
@@ -85,11 +115,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 +126,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 +146,43 @@ 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>
-    `;
-
-    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 title. */
+  renderTitle(): MarkupElement {
+    return el(
+      'g',
+      {
+        'data-testid': 'card-title',
+        transform: `translate(${this.paddingX}, ${this.paddingY})`,
+      },
+      flexLayout({
+        items: [
+          this.titlePrefixIcon &&
+            el(
+              'svg',
+              {
+                class: '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,
+      }),
+    );
   }
 
-  /**
-   * @returns The rendered card gradient.
-   */
-  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>`;
-    };
-
+  /** @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 +197,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 +222,18 @@ 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('.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 +249,64 @@ 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': 'titleId descId',
+        },
+        el('title', { id: 'titleId' }, this.a11yTitle),
+        el('desc', { id: 'descId' }, this.a11yDesc),
+        style(
+          rule('.header', {
+            font: "600 18px 'Segoe UI', Ubuntu, Sans-Serif",
+            fill: this.colors.light.titleColor,
+            animation: 'fadeInAnimation 0.8s ease-in-out forwards',
+          }),
+          atRule(
+            '@supports(-moz-appearance: auto)',
+            cssComment('Selector detects Firefox'),
+            rule('.header', { 'font-size': '15.5px' }),
+          ),
+          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.renderTitle(),
+        el(
+          'g',
+          {
+            'data-testid': 'main-card-body',
+            transform: `translate(0, ${this.hideTitle ? this.paddingX : this.paddingY + 20})`,
+          },
+          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,
@@ -30,11 +25,13 @@ class I18n<Translations extends TranslationsMap = TranslationsMap> {
   /**
    * Get translation.
    *
-   * @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`);
     }