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

package/src/cards/top-languages.ts

@@ -1,3 +1,4 @@
+import { CARD_ICON, CARD_WIDTH, FONT_WEIGHT, firefoxFontSize, font } from '../common/brand.ts';
 import { Card } from '../common/Card.ts';
 import { getLightDarkColors, isPrefixedHexColor } from '../common/color.ts';
 import { formatBytes } from '../common/fmt.ts';
@@ -7,12 +8,12 @@ import { chunkArray, clampValue, lowercaseTrim } from '../common/ops.ts';
 import { createProgressNode, flexLayout, measureText } from '../common/render.ts';
 import type { Lang, TopLangData } from '../fetchers/types.ts';
 import type { Child, MarkupElement } from '../markup/index.ts';
-import { atRule, cssComment, el, rule } from '../markup/index.ts';
+import { atRule, el, rule } from '../markup/index.ts';
 import { langCardLocales } from '../translations.ts';
 
 import type { CardOptions, CommonCardOptions } from './options.ts';
 
-const DEFAULT_CARD_WIDTH = 300;
+const DEFAULT_CARD_WIDTH = CARD_WIDTH.compact;
 const MIN_CARD_WIDTH = 280;
 const CARD_PADDING = 25;
 const COMPACT_LAYOUT_BASE_HEIGHT = 90;
@@ -21,6 +22,8 @@ const MAXIMUM_LANGS_COUNT = 20;
 const NORMAL_LAYOUT_DEFAULT_LANGS_COUNT = 5;
 const COMPACT_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 const DONUT_LAYOUT_DEFAULT_LANGS_COUNT = 5;
+/** Room for the chart that sits beside the language list. */
+const DONUT_EXTRA_WIDTH = 50;
 const PIE_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 const DONUT_VERTICAL_LAYOUT_DEFAULT_LANGS_COUNT = 6;
 
@@ -801,10 +804,7 @@ const getDefaultLanguagesCountByLayout = ({
  *
  * @returns Language card SVG object.
  */
-const renderTopLanguages = (
-  topLangs: TopLangData,
-  options: CardOptions<TopLangOptions> = {},
-): string => {
+const renderCard = (topLangs: TopLangData, options: CardOptions<TopLangOptions> = {}): string => {
   const {
     hide_title = false,
     hide_border = false,
@@ -865,7 +865,9 @@ const renderTopLanguages = (
     );
   } else if (layout === 'donut') {
     height = calculateDonutLayoutHeight(langs.length);
-    width += 50; // padding
+    // A donut defaults a step wider so the chart has its room; a width asked for
+    // explicitly keeps the extra it has always been given instead of being snapped.
+    width = width === DEFAULT_CARD_WIDTH ? CARD_WIDTH.standard : width + DONUT_EXTRA_WIDTH;
     finalLayout = renderDonutLayout(langs, width, totalLanguageSize, stats_format, hide_values);
   } else {
     finalLayout = renderNormalLayout(langs, width, totalLanguageSize, stats_format, hide_values);
@@ -874,6 +876,7 @@ const renderTopLanguages = (
   const card = new Card({
     customTitle: custom_title,
     defaultTitle: i18n.t('langcard.title'),
+    titlePrefixIcon: CARD_ICON.topLanguages,
     width,
     height,
     border_radius,
@@ -901,16 +904,12 @@ const renderTopLanguages = (
         rule('to', { width: '100%' }),
       ),
       rule('.stat', {
-        font: `600 14px 'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif`,
+        font: font('regular', 'body'),
         fill: textColor,
       }),
-      atRule(
-        '@supports(-moz-appearance: auto)',
-        cssComment('Selector detects Firefox'),
-        rule('.stat', { 'font-size': '12px' }),
-      ),
-      rule('.bold', { 'font-weight': 700 }),
-      rule('.lang-name', { font: '400 11px "Segoe UI", Ubuntu, Sans-Serif', fill: textColor }),
+      firefoxFontSize(['.stat'], 'small'),
+      rule('.bold', { 'font-weight': FONT_WEIGHT.semibold }),
+      rule('.lang-name', { font: font('regular', 'micro'), fill: textColor }),
       rule('.stagger', { opacity: 0, animation: 'fadeInAnimation 0.3s ease-in-out forwards' }),
       rule('#rect-mask rect', { animation: 'slideInAnimation 1s ease-in-out forwards' }),
       rule('.lang-progress', { animation: 'growWidthAnimation 0.6s ease-in-out forwards' }),
@@ -939,6 +938,18 @@ const renderTopLanguages = (
   return card.render(el('svg', { 'data-testid': 'lang-items', x: CARD_PADDING }, finalLayout));
 };
 
+/**
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * They ride on the renderer so a list cannot be found without what draws it;
+ * the api handler forwards them onto its own export, which is what a UI reads.
+ */
+const renderTopLanguages = Object.assign(renderCard, {
+  OPTIONS: {
+    layout: TOP_LANG_LAYOUTS,
+    stats_format: TOP_LANG_STATS_FORMATS,
+  },
+});
+
 export {
   getLongestLang,
   degreesToRadians,
@@ -953,9 +964,7 @@ export {
   calculatePieLayoutHeight,
   donutCenterTranslation,
   trimTopLanguages,
-  renderTopLanguages,
   MIN_CARD_WIDTH,
   getDefaultLanguagesCountByLayout,
-  TOP_LANG_LAYOUTS,
-  TOP_LANG_STATS_FORMATS,
+  renderTopLanguages,
 };

package/src/cards/wakatime.ts

@@ -1,3 +1,4 @@
+import { CARD_ICON, CARD_WIDTH, FONT_WEIGHT, firefoxFontSize, font } from '../common/brand.ts';
 import { Card } from '../common/Card.ts';
 import { getLightDarkColors, isPrefixedHexColor } from '../common/color.ts';
 import { I18n } from '../common/I18n.ts';
@@ -6,12 +7,12 @@ import { clampValue, lowercaseTrim } from '../common/ops.ts';
 import { createProgressNode, flexLayout } from '../common/render.ts';
 import type { WakaTimeData, WakaTimeLang } from '../fetchers/types.ts';
 import type { Child, CssChild, MarkupElement } from '../markup/index.ts';
-import { atRule, cssComment, el, rule } from '../markup/index.ts';
+import { atRule, el, rule } from '../markup/index.ts';
 import { wakatimeCardLocales } from '../translations.ts';
 
 import type { CardOptions, CommonCardOptions } from './options.ts';
 
-const DEFAULT_CARD_WIDTH = 495;
+const DEFAULT_CARD_WIDTH = CARD_WIDTH.wide;
 const MIN_CARD_WIDTH = 250;
 const COMPACT_LAYOUT_MIN_WIDTH = 400;
 const DEFAULT_LINE_HEIGHT = 25;
@@ -216,17 +217,13 @@ const getStyles = ({ textColor }: { textColor: string }): Array<CssChild> => {
 
   return [
     rule('.stat', {
-      font: `600 14px 'Segoe UI', Ubuntu, "Helvetica Neue", Sans-Serif`,
+      font: font('regular', 'body'),
       fill: textColor,
     }),
-    atRule(
-      '@supports(-moz-appearance: auto)',
-      cssComment('Selector detects Firefox'),
-      rule('.stat', { 'font-size': '12px' }),
-    ),
+    firefoxFontSize(['.stat'], 'small'),
     rule('.stagger', { opacity: 0, animation: 'fadeInAnimation 0.3s ease-in-out forwards' }),
-    rule('.not_bold', { 'font-weight': 400 }),
-    rule('.bold', { 'font-weight': 700 }),
+    rule('.not_bold', { 'font-weight': FONT_WEIGHT.regular }),
+    rule('.bold', { 'font-weight': FONT_WEIGHT.semibold }),
   ];
 };
 
@@ -257,7 +254,7 @@ const normalizeCardWidth = ({
  *
  * @returns WakaTime card SVG.
  */
-const renderWakatimeCard = (
+const renderCard = (
   stats: Partial<WakaTimeData> = {},
   options: CardOptions<WakaTimeOptions> = {},
 ): string => {
@@ -412,6 +409,7 @@ const renderWakatimeCard = (
   const card = new Card({
     customTitle: custom_title,
     defaultTitle: titleText,
+    titlePrefixIcon: CARD_ICON.wakatime,
     width: normalizedWidth,
     height,
     border_radius,
@@ -439,7 +437,7 @@ const renderWakatimeCard = (
         rule('from', { width: 0 }),
         rule('to', { width: '100%' }),
       ),
-      rule('.lang-name', { font: "400 11px 'Segoe UI', Ubuntu, Sans-Serif", fill: textColor }),
+      rule('.lang-name', { font: font('regular', 'micro'), fill: textColor }),
       rule('#rect-mask rect', { animation: 'slideInAnimation 1s ease-in-out forwards' }),
       rule('.lang-progress', {
         animation: 'growWidthAnimation 0.6s ease-in-out forwards',
@@ -470,4 +468,16 @@ const renderWakatimeCard = (
   return card.render(el('svg', { x: 0, y: 0, width: '100%' }, finalLayout));
 };
 
-export { DISPLAY_FORMATS, WAKATIME_LAYOUTS, renderWakatimeCard };
+/**
+ * The card, and the values each of its options accepts, keyed by the option's own name.
+ * They ride on the renderer so a list cannot be found without what draws it;
+ * the api handler forwards them onto its own export, which is what a UI reads.
+ */
+const renderWakatimeCard = Object.assign(renderCard, {
+  OPTIONS: {
+    layout: WAKATIME_LAYOUTS,
+    display_format: DISPLAY_FORMATS,
+  },
+});
+
+export { renderWakatimeCard };

package/src/common/Card.ts

@@ -1,6 +1,7 @@
 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';
@@ -104,7 +105,7 @@ class Card {
     this.darkCss = [];
 
     this.paddingX = 25;
-    this.paddingY = 35;
+    this.paddingY = 30;
     this.titlePrefixIcon = titlePrefixIcon;
     this.animations = true;
     this.a11yTitle = '';
@@ -164,7 +165,7 @@ class Card {
             el(
               'svg',
               {
-                class: 'icon',
+                class: 'title-icon',
                 x: 0,
                 y: -13,
                 viewBox: '0 0 16 16',
@@ -178,9 +179,41 @@ class Card {
         ],
         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,
+      }),
     );
   }
 
+  /** Where the body starts, and so where the title band ends. */
+  private get bodyOffset(): number {
+    return this.hideTitle ? this.paddingX : this.paddingY + 25;
+  }
+
+  /**
+   * 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.
+   */
+  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 (
@@ -225,6 +258,9 @@ class Card {
     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,
     );
@@ -259,21 +295,29 @@ class Card {
           fill: 'none',
           xmlns: 'http://www.w3.org/2000/svg',
           role: 'img',
-          'aria-labelledby': 'titleId descId',
+          'aria-labelledby': 'title-id desc-id',
         },
-        el('title', { id: 'titleId' }, this.a11yTitle),
-        el('desc', { id: 'descId' }, this.a11yDesc),
+        el('title', { id: 'title-id' }, this.a11yTitle),
+        el('desc', { id: 'desc-id' }, this.a11yDesc),
         style(
           rule('.header', {
-            font: "600 18px 'Segoe UI', Ubuntu, Sans-Serif",
+            font: font('semibold', 'title'),
             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' }),
+          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(),
@@ -295,12 +339,13 @@ class Card {
               : 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.hideTitle ? this.paddingX : this.paddingY + 20})`,
+            transform: `translate(0, ${this.bodyOffset})`,
           },
           body,
         ),

package/src/common/I18n.ts

@@ -23,7 +23,7 @@ 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.
    *
    * @returns Translated string.
    */
@@ -36,7 +36,9 @@ class I18n<Translations extends TranslationsMap = TranslationsMap> {
       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,
+};

package/src/common/constants.ts

@@ -1,5 +1,8 @@
 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. */
+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;
 
@@ -12,4 +15,4 @@ const OWNER_AFFILIATIONS: Array<RepositoryAffiliation> = [
   'ORGANIZATION_MEMBER',
 ];
 
-export { GITHUB_USERNAME_PATTERN, OWNER_AFFILIATIONS };
+export { GITHUB_EPOCH_YEAR, GITHUB_USERNAME_PATTERN, OWNER_AFFILIATIONS };

package/src/common/date.ts

@@ -1,4 +1,8 @@
-/** 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. */
+
+import { GITHUB_EPOCH_YEAR } from './constants.ts';
+
+/** A range between two dates, as GitHub's range arguments take it. */
 interface GitHubDateRange {
   /** Start of the range, inclusive. */
   from: Date;
@@ -6,6 +10,9 @@ interface GitHubDateRange {
   to: Date;
 }
 
+/** 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.
@@ -15,7 +22,7 @@ interface GitHubDateRange {
 const toGitHubDateTime = (date: Date): string => `${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`,
@@ -28,5 +35,130 @@ const getGitHubYearRange = (year: number): GitHubDateRange => ({
   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 = (): GitHubDateRange => ({
+  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: Date | undefined, to: Date | undefined): GitHubDateRange => {
+  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: string, end: 'from' | 'to'): Date | undefined => {
+  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 }: GitHubDateRange): Array<GitHubDateRange> => {
+  const ranges: Array<GitHubDateRange> = [];
+  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: number, last: number): string =>
+  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 }: GitHubDateRange): string => {
+  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: ReadonlyArray<number>,
+  range: GitHubDateRange,
+): Array<GitHubDateRange> => {
+  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,
+};
 export type { GitHubDateRange };

package/src/common/icons.ts

@@ -51,11 +51,7 @@ const icons = {
     'fill-rule': 'evenodd',
     d: 'M8 1.5a6.5 6.5 0 100 13 6.5 6.5 0 000-13zM0 8a8 8 0 1116 0A8 8 0 010 8zm9 3a1 1 0 11-2 0 1 1 0 012 0zm-.25-6.25a.75.75 0 00-1.5 0v3.5a.75.75 0 001.5 0v-3.5z',
   }),
-  icon: el('path', {
-    'fill-rule': 'evenodd',
-    d: 'M2 2.5A2.5 2.5 0 014.5 0h8.75a.75.75 0 01.75.75v12.5a.75.75 0 01-.75.75h-2.5a.75.75 0 110-1.5h1.75v-2h-8a1 1 0 00-.714 1.7.75.75 0 01-1.072 1.05A2.495 2.495 0 012 11.5v-9zm10.5-1V9h-8c-.356 0-.694.074-1 .208V2.5a1 1 0 011-1h8zM5 12.25v3.25a.25.25 0 00.4.2l1.45-1.087a.25.25 0 01.3 0L8.6 15.7a.25.25 0 00.4-.2v-3.25a.25.25 0 00-.25-.25h-3.5a.25.25 0 00-.25.25z',
-  }),
-  contribs: el('path', {
+  repo: el('path', {
     'fill-rule': 'evenodd',
     d: 'M2 2.5A2.5 2.5 0 014.5 0h8.75a.75.75 0 01.75.75v12.5a.75.75 0 01-.75.75h-2.5a.75.75 0 110-1.5h1.75v-2h-8a1 1 0 00-.714 1.7.75.75 0 01-1.072 1.05A2.495 2.495 0 012 11.5v-9zm10.5-1V9h-8c-.356 0-.694.074-1 .208V2.5a1 1 0 011-1h8zM5 12.25v3.25a.25.25 0 00.4.2l1.45-1.087a.25.25 0 01.3 0L8.6 15.7a.25.25 0 00.4-.2v-3.25a.25.25 0 00-.25-.25h-3.5a.25.25 0 00-.25.25z',
   }),
@@ -85,6 +81,15 @@ const icons = {
     'fill-rule': 'evenodd',
     d: 'M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v12.5A1.75 1.75 0 0 1 14.25 16H1.75A1.75 1.75 0 0 1 0 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V1.75a.25.25 0 0 0-.25-.25Zm7.47 3.97a.75.75 0 0 1 1.06 0l2 2a.75.75 0 0 1 0 1.06l-2 2a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L10.69 8 9.22 6.53a.75.75 0 0 1 0-1.06ZM6.78 6.53 5.31 8l1.47 1.47a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215l-2-2a.75.75 0 0 1 0-1.06l2-2a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042Z',
   }),
+  pulse: el('path', {
+    d: 'M6 2c.306 0 .582.187.696.471L10 10.731l1.304-3.26A.751.751 0 0 1 12 7h3.25a.75.75 0 0 1 0 1.5h-2.742l-1.812 4.529a.751.751 0 0 1-1.392 0L6 4.769l-1.304 3.26A.751.751 0 0 1 4 8.5H.75a.75.75 0 0 1 0-1.5h2.742l1.812-4.529A.751.751 0 0 1 6 2Z',
+  }),
+  code: el('path', {
+    d: 'M4.72 3.22a.75.75 0 0 1 1.06 1.06L2.06 8l3.72 3.72a.75.75 0 1 1-1.06 1.06L.47 8.53a.75.75 0 0 1 0-1.06Zm6.56 0a.75.75 0 1 0-1.06 1.06L13.94 8l-3.72 3.72a.75.75 0 1 0 1.06 1.06l4.25-4.25a.75.75 0 0 0 0-1.06Z',
+  }),
+  clock: el('path', {
+    d: 'M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm7-3.25v2.992l2.028.812a.75.75 0 0 1-.557 1.392l-2.5-1A.75.75 0 0 1 7 8.25v-3.5a.75.75 0 0 1 1.5 0Z',
+  }),
 };
 
 /** Attributes every rank glyph shares, so the three variants differ only where they mean to. */