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

package/build/common/Card.js

@@ -1,4 +1,5 @@
 import { atRule, cssComment, el, renderMarkup, rule, style } from '../markup/index.js';
+import { ACCENT, firefoxFontSize, font, TITLE_BAND, TITLE_FIREFOX_SIZE } from './brand.js';
 import { getCardColors, isPrefixedHexColor, isValidGradient } from './color.js';
 import { flexLayout } from './render.js';
 /** Stops every animation, whether the reader asked or the card did. */
@@ -59,7 +60,7 @@ class Card {
         this.css = [];
         this.darkCss = [];
         this.paddingX = 25;
-        this.paddingY = 35;
+        this.paddingY = 30;
         this.titlePrefixIcon = titlePrefixIcon;
         this.animations = true;
         this.a11yTitle = '';
@@ -107,7 +108,7 @@ class Card {
             items: [
                 this.titlePrefixIcon &&
                     el('svg', {
-                        class: 'icon',
+                        class: 'title-icon',
                         x: 0,
                         y: -13,
                         viewBox: '0 0 16 16',
@@ -118,8 +119,36 @@ class Card {
                 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,
         }));
     }
+    /** Where the body starts, and so where the title band ends. */
+    get bodyOffset() {
+        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.
+     */
+    renderTitleBand() {
+        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() {
         if (typeof this.colors.light.bgColor === 'object' &&
@@ -151,7 +180,7 @@ class Card {
         const bgFill = typeof this.colors.dark.bgColor === 'object'
             ? 'url(#gradient-dark)'
             : this.colors.dark.bgColor;
-        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);
+        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);
     }
     /** @returns The rendered card. */
     render(body) {
@@ -176,12 +205,18 @@ class Card {
             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",
+            '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',
-        }), 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', {
+        }), 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,
@@ -194,9 +229,9 @@ class Card {
                 ? 'url(#gradient)'
                 : this.colors.light.bgColor,
             'stroke-opacity': this.hideBorder ? 0 : 1,
-        }), !this.hideTitle && this.renderTitle(), el('g', {
+        }), !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/build/common/I18n.d.ts

@@ -11,7 +11,7 @@ declare class I18n<Translations extends TranslationsMap = TranslationsMap> {
         translations: Translations;
     });
     /**
-     * Get translation.
+     * Get translation, falling back to the English string when the locale has no entry for the key.
      *
      * @returns Translated string.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"I18n.d.ts","sourceRoot":"","sources":["../../src/common/I18n.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,cAAM,IAAI,CAAC,YAAY,SAAS,eAAe,GAAG,eAAe;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,CAAC;IAE3B,YAAY,EACV,MAAM,EACN,YAAY,GACb,EAAE;QAED,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,YAAY,EAAE,YAAY,CAAC;KAC5B,EAGA;IAED;;;;OAIG;IACH,CAAC,CAAC,GAAG,EAAE,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAe1C;CACF;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"I18n.d.ts","sourceRoot":"","sources":["../../src/common/I18n.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D;;GAEG;AACH,cAAM,IAAI,CAAC,YAAY,SAAS,eAAe,GAAG,eAAe;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,YAAY,CAAC;IAE3B,YAAY,EACV,MAAM,EACN,YAAY,GACb,EAAE;QAED,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,YAAY,EAAE,YAAY,CAAC;KAC5B,EAGA;IAED;;;;OAIG;IACH,CAAC,CAAC,GAAG,EAAE,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAiB1C;CACF;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/build/common/I18n.js

@@ -10,7 +10,7 @@ class I18n {
         this.translations = translations;
     }
     /**
-     * Get translation.
+     * Get translation, falling back to the English string when the locale has no entry for the key.
      *
      * @returns Translated string.
      */
@@ -22,7 +22,9 @@ class I18n {
         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/build/common/brand.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 { CssChild } from '../markup/index.ts';
+/** The type scale, in px. */
+declare const FONT_SIZE: {
+    readonly display: 22;
+    readonly title: 18;
+    readonly lead: 16;
+    readonly body: 14;
+    readonly meta: 13;
+    readonly small: 12;
+    readonly micro: 11;
+};
+/**
+ * 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.
+ */
+declare const TITLE_FIREFOX_SIZE = 15.5;
+/** `regular` labels, `semibold` the values they label, `bold` the rank glyph alone. */
+declare const FONT_WEIGHT: {
+    readonly regular: 400;
+    readonly semibold: 600;
+    readonly bold: 700;
+};
+type FontSize = keyof typeof FONT_SIZE;
+type FontWeight = keyof typeof FONT_WEIGHT;
+/** @returns The `font` shorthand for one step of the scale. */
+declare const font: (weight: FontWeight, size: FontSize) => string;
+/**
+ * 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.
+ */
+declare const firefoxFontSize: (selectors: Array<string>, size: FontSize | number) => CssChild;
+/**
+ * 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.
+ */
+declare const CARD_WIDTH: {
+    readonly compact: 300;
+    readonly standard: 400;
+    readonly wide: 500;
+};
+/** The tinted band behind every card title: the mark a card is recognized by. */
+declare const TITLE_BAND: {
+    /** Enough to read as a band on every theme, little enough to leave the title legible. */
+    readonly opacity: 0.08;
+    /** Clear air the band leaves between its foot and the first row of the body. */
+    readonly gap: 9;
+};
+/** The rule under the title icon, sitting inside the band. */
+declare const ACCENT: {
+    readonly width: 32;
+    readonly height: 2;
+    /** Below the title's descenders, clear of the band's foot. */
+    readonly y: 8;
+};
+/**
+ * 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.
+ */
+declare const CARD_ICON: {
+    contributedTo: import("../markup/element.ts").MarkupElement;
+    gist: import("../markup/element.ts").MarkupElement;
+    repo: import("../markup/element.ts").MarkupElement;
+    stats: import("../markup/element.ts").MarkupElement;
+    topLanguages: import("../markup/element.ts").MarkupElement;
+    wakatime: import("../markup/element.ts").MarkupElement;
+};
+export { ACCENT, CARD_ICON, CARD_WIDTH, FONT_SIZE, FONT_WEIGHT, firefoxFontSize, font, TITLE_BAND, TITLE_FIREFOX_SIZE, };
+//# sourceMappingURL=brand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/common/brand.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAS,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAO1D,6BAA6B;AAC7B,QAAA,MAAM,SAAS;aACb,OAAO,EAAE,EAAE;aACX,KAAK,EAAE,EAAE;aACT,IAAI,EAAE,EAAE;aACR,IAAI,EAAE,EAAE;aACR,IAAI,EAAE,EAAE;aACR,KAAK,EAAE,EAAE;aACT,KAAK,EAAE,EAAE;CACD,CAAC;AAEX;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,OAAO,CAAC;AAEhC,uFAAuF;AACvF,QAAA,MAAM,WAAW;aACf,OAAO,EAAE,GAAG;aACZ,QAAQ,EAAE,GAAG;aACb,IAAI,EAAE,GAAG;CACD,CAAC;AAEX,KAAK,QAAQ,GAAG,MAAM,OAAO,SAAS,CAAC;AACvC,KAAK,UAAU,GAAG,MAAM,OAAO,WAAW,CAAC;AAE3C,+DAA+D;AAC/D,QAAA,MAAM,IAAI,WAAY,UAAU,QAAQ,QAAQ,KAAG,MAC0B,CAAC;AAE9E;;;;;GAKG;AACH,QAAA,MAAM,eAAe,cAAe,KAAK,CAAC,MAAM,CAAC,QAAQ,QAAQ,GAAG,MAAM,KAAG,QAO5E,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,UAAU;aACd,OAAO,EAAE,GAAG;aACZ,QAAQ,EAAE,GAAG;aACb,IAAI,EAAE,GAAG;CACD,CAAC;AAEX,iFAAiF;AACjF,QAAA,MAAM,UAAU;IACd,yFAAyF;aACzF,OAAO,EAAE,IAAI;IACb,gFAAgF;aAChF,GAAG,EAAE,CAAC;CACE,CAAC;AAEX,8DAA8D;AAC9D,QAAA,MAAM,MAAM;aACV,KAAK,EAAE,EAAE;aACT,MAAM,EAAE,CAAC;IACT,8DAA8D;aAC9D,CAAC,EAAE,CAAC;CACI,CAAC;AAEX;;;GAGG;AACH,QAAA,MAAM,SAAS;;;;;;;CAOkB,CAAC;AAElC,OAAO,EACL,MAAM,EACN,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,IAAI,EACJ,UAAU,EACV,kBAAkB,GACnB,CAAC"}

package/build/common/brand.js

@@ -0,0 +1,73 @@
+import { atRule, cssComment, rule } from '../markup/index.js';
+import { icons } from './icons.js';
+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,
+};
+/**
+ * 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,
+};
+/** @returns The `font` shorthand for one step of the scale. */
+const font = (weight, size) => `${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, size) => {
+    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,
+};
+/** 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,
+};
+/** 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,
+};
+/**
+ * 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,
+};
+export { ACCENT, CARD_ICON, CARD_WIDTH, FONT_SIZE, FONT_WEIGHT, firefoxFontSize, font, TITLE_BAND, TITLE_FIREFOX_SIZE, };

package/build/common/constants.d.ts

@@ -1,9 +1,11 @@
 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 { GITHUB_USERNAME_PATTERN, 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,qFAAqF;AACrF,QAAA,MAAM,uBAAuB,QAA6C,CAAC;AAE3E;;GAEG;AACH,QAAA,MAAM,kBAAkB,EAAE,KAAK,CAAC,qBAAqB,CAIpD,CAAC;AAEF,OAAO,EAAE,uBAAuB,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,5 @@
+/** 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;
 /**
@@ -8,4 +10,4 @@ const OWNER_AFFILIATIONS = [
     'COLLABORATOR',
     'ORGANIZATION_MEMBER',
 ];
-export { GITHUB_USERNAME_PATTERN, 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;
@@ -13,7 +14,7 @@ interface GitHubDateRange {
  */
 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`,
@@ -22,6 +23,52 @@ declare const toGitHubDateTime: (date: Date) => string;
  * @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;;;;;GAKG;AACH,QAAA,MAAM,gBAAgB,SAAU,IAAI,KAAG,MAA+C,CAAC;AAEvF;;;;;;;;GAQG;AACH,QAAA,MAAM,kBAAkB,SAAU,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,3 +1,7 @@
+/** @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.
@@ -6,7 +10,7 @@
  */
 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`,
@@ -18,4 +22,102 @@ 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/icons.d.ts

@@ -6,8 +6,7 @@ declare const icons: {
     prs_merged: import("../markup/element.ts").MarkupElement;
     prs_merged_percentage: import("../markup/element.ts").MarkupElement;
     issues: import("../markup/element.ts").MarkupElement;
-    icon: import("../markup/element.ts").MarkupElement;
-    contribs: import("../markup/element.ts").MarkupElement;
+    repo: import("../markup/element.ts").MarkupElement;
     fork: import("../markup/element.ts").MarkupElement;
     reviews: import("../markup/element.ts").MarkupElement;
     discussions_started: import("../markup/element.ts").MarkupElement;
@@ -15,6 +14,9 @@ declare const icons: {
     comments: import("../markup/element.ts").MarkupElement;
     contributions: import("../markup/element.ts").MarkupElement;
     gist: import("../markup/element.ts").MarkupElement;
+    pulse: import("../markup/element.ts").MarkupElement;
+    code: import("../markup/element.ts").MarkupElement;
+    clock: import("../markup/element.ts").MarkupElement;
 };
 /**
  * Get rank icon

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

@@ -1 +1 @@
-{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../../src/common/icons.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD,QAAA,MAAM,KAAK;IACT,IAAI;IAIJ,OAAO;IAIP,GAAG;IAIH,UAAU;IAIV,qBAAqB;IAIrB,MAAM;IAIN,IAAI;IAIJ,QAAQ;IAIR,IAAI;IAIJ,OAAO;IAIP,mBAAmB;IAInB,oBAAoB;IAIpB,QAAQ;IAGR,aAAa;IAGb,IAAI;CAIL,CAAC;AAUF;;;;GAIG;AACH,QAAA,MAAM,QAAQ,SAAU,MAAM,aAAa,MAAM,cAAc,MAAM,KAAG,KAkDvE,CAAC;AAEF,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"icons.d.ts","sourceRoot":"","sources":["../../src/common/icons.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD,QAAA,MAAM,KAAK;IACT,IAAI;IAIJ,OAAO;IAIP,GAAG;IAIH,UAAU;IAIV,qBAAqB;IAIrB,MAAM;IAIN,IAAI;IAIJ,IAAI;IAIJ,OAAO;IAIP,mBAAmB;IAInB,oBAAoB;IAIpB,QAAQ;IAGR,aAAa;IAGb,IAAI;IAIJ,KAAK;IAGL,IAAI;IAGJ,KAAK;CAGN,CAAC;AAUF;;;;GAIG;AACH,QAAA,MAAM,QAAQ,SAAU,MAAM,aAAa,MAAM,cAAc,MAAM,KAAG,KAkDvE,CAAC;AAEF,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC"}

package/build/common/icons.js

@@ -24,11 +24,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',
     }),
@@ -58,6 +54,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. */
 const RANK_TEXT = {

package/build/common/ops.d.ts

@@ -14,9 +14,9 @@ declare const parseArray: (str: string | undefined) => Array<string>;
 /**
  * Clamp the given number between the given range.
  *
- * @returns The clamped number.
+ * @returns The clamped number; `min` for `NaN`.
  */
-declare const clampValue: (number: string | number, min: number, max: number) => number;
+declare const clampValue: (number: number, min: number, max: number) => number;
 /**
  * Lowercase and trim string.
  *
@@ -43,6 +43,11 @@ declare const parseEmojis: (str: string) => string;
  * @returns Parsed affiliations.
  */
 declare const parseOwnerAffiliations: (affiliations: Array<string>) => Array<RepositoryAffiliation>;
-declare const buildSearchFilter: (repos?: Array<string> | string, owners?: Array<string> | string) => string;
+/**
+ * The qualifiers that scope a REST search to repositories and owners.
+ *
+ * @returns e.g. `repo:a/b owner:c `, each qualifier followed by a space; empty when both lists are.
+ */
+declare const buildSearchFilter: (repos: Array<string>, owners: Array<string>) => string;
 export { parseBoolean, parseArray, clampValue, lowercaseTrim, chunkArray, parseEmojis, parseOwnerAffiliations, buildSearchFilter, };
 //# sourceMappingURL=ops.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/common/ops.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAM5E;;;;GAIG;AACH,QAAA,MAAM,YAAY,UAAW,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,OAAO,GAAG,SAcrE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,UAAU,QAAS,MAAM,GAAG,SAAS,KAAG,KAAK,CAAC,MAAM,CAKzD,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,UAAU,WAAY,MAAM,GAAG,MAAM,OAAO,MAAM,OAAO,MAAM,KAAG,MAKvE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,aAAa,SAAU,MAAM,KAAG,MAAmC,CAAC;AAE1E;;;;GAIG;AACH,QAAA,MAAM,UAAU,GAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAStE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,WAAW,QAAS,MAAM,KAAG,MASlC,CAAC;AAKF;;;;;;GAMG;AACH,QAAA,MAAM,sBAAsB,iBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,qBAAqB,CAYxF,CAAC;AAEF,QAAA,MAAM,iBAAiB,WACd,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,WACrB,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,KAC7B,MAQF,CAAC;AAEF,OAAO,EACL,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,iBAAiB,GAClB,CAAC"}
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../../src/common/ops.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAM5E;;;;GAIG;AACH,QAAA,MAAM,YAAY,UAAW,MAAM,GAAG,OAAO,GAAG,SAAS,KAAG,OAAO,GAAG,SAcrE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,UAAU,QAAS,MAAM,GAAG,SAAS,KAAG,KAAK,CAAC,MAAM,CAKzD,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,UAAU,WAAY,MAAM,OAAO,MAAM,OAAO,MAAM,KAAG,MACI,CAAC;AAEpE;;;;GAIG;AACH,QAAA,MAAM,aAAa,SAAU,MAAM,KAAG,MAAmC,CAAC;AAE1E;;;;GAIG;AACH,QAAA,MAAM,UAAU,GAAI,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,MAAM,KAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAStE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,WAAW,QAAS,MAAM,KAAG,MASlC,CAAC;AAKF;;;;;;GAMG;AACH,QAAA,MAAM,sBAAsB,iBAAkB,KAAK,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,qBAAqB,CAYxF,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,iBAAiB,UAAW,KAAK,CAAC,MAAM,CAAC,UAAU,KAAK,CAAC,MAAM,CAAC,KAAG,MACwB,CAAC;AAElG,OAAO,EACL,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,iBAAiB,GAClB,CAAC"}