contrib-graphs 0.0.0-stage → 0.1.0

package/dist/data-DptvXfjH.d.ts

@@ -0,0 +1,344 @@
+
+import { CSSProperties, ReactNode } from "react";
+/** Colors of levels 0 to 4. */
+type LevelColors = readonly [string, string, string, string, string];
+/** Colors for one color mode. */
+interface ThemePalette {
+  /** Colors of levels 0 to 4. */
+  levels: LevelColors;
+  text: string;
+  muted: string;
+  /** Background of variants with their own surface, such as Terminal. */
+  surface: string;
+  border: string;
+}
+/** A theme: a name plus a light and a dark palette. */
+interface GraphTheme {
+  name: string;
+  light: ThemePalette;
+  dark: ThemePalette;
+}
+/** Built-in themes: `github`, `gitlab`, `frost`, `ember`, `violet` and `mono`. */
+declare const themes: {
+  github: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+  };
+  gitlab: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      surface: string;
+      border: string;
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+    };
+  };
+  frost: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      surface: string;
+      border: string;
+      text: string;
+      muted: string;
+      levels: [string, string, string, string, string];
+    };
+  };
+  ember: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      surface: string;
+      border: string;
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+    };
+  };
+  violet: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      surface: string;
+      border: string;
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+    };
+  };
+  mono: {
+    name: string;
+    light: {
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+      surface: string;
+      border: string;
+    };
+    dark: {
+      surface: string;
+      border: string;
+      levels: [string, string, string, string, string];
+      text: string;
+      muted: string;
+    };
+  };
+};
+/** Name of a built-in theme. */
+type ThemeName = keyof typeof themes;
+/** Names of the built-in themes. */
+declare const themeNames: ThemeName[];
+/** Returns the theme object for a preset name or a custom theme; unknown names fall back to `github`. */
+declare function resolveTheme(theme: ThemeName | GraphTheme | undefined): GraphTheme;
+/** Turns a theme into CSS variables (`--cg-l0-light`, `--cg-l0-dark`…); the stylesheet picks light or dark. */
+declare function themeVars(theme: GraphTheme): CSSProperties;
+/** One day of activity. `date` uses the ISO format `YYYY-MM-DD`. */
+interface ContributionDay {
+  date: string;
+  count: number;
+}
+/** Intensity level from 0 (no activity) to 4 (busiest). */
+type Level = 0 | 1 | 2 | 3 | 4;
+/**
+ * How each count maps to a level from 0 to 4.
+ * - `quantile`: by quartiles of the active days (like GitHub)
+ * - `linear`: proportional to the maximum
+ * - `[a, b, c, d]`: minimum count for levels 1, 2, 3 and 4
+ */
+type LevelScale = 'quantile' | 'linear' | readonly [number, number, number, number];
+/** `auto` follows `prefers-color-scheme`, or `data-theme="light|dark"` on `<html>`. */
+type ColorMode = 'auto' | 'light' | 'dark';
+/** A day as laid out in the calendar, with its level and position. */
+interface CalendarDay extends ContributionDay {
+  level: Level;
+  /** Flat index in `calendar.days`. */
+  index: number;
+  /** Column (week) in the calendar. */
+  weekIndex: number;
+  /** Row from 0 to 6, relative to `weekStart`. */
+  dayIndex: number;
+  /** Actual day of the week, 0 = Sunday. */
+  weekday: number;
+}
+/** A month label and the week column where it starts. */
+interface MonthLabel {
+  label: string;
+  weekIndex: number;
+  month: number;
+  year: number;
+}
+/** The result of `buildCalendar`: a weeks × 7 grid plus totals and month labels. */
+interface Calendar {
+  weeks: (CalendarDay | null)[][];
+  days: CalendarDay[];
+  months: MonthLabel[];
+  total: number;
+  max: number;
+  start: string;
+  end: string;
+  levelOf: (count: number) => Level;
+}
+/** Props shared by every graph. */
+interface BaseGraphProps {
+  /** Days of activity. Missing days count as 0 and duplicate dates are added up. */
+  data: ContributionDay[];
+  /**
+   * A preset name or your own theme object.
+   * @default 'github'
+   */
+  theme?: ThemeName | GraphTheme;
+  /**
+   * `auto` follows `prefers-color-scheme`, or `data-theme="light|dark"` on `<html>`.
+   * @default 'auto'
+   */
+  colorMode?: ColorMode;
+  /**
+   * Number of weeks to show.
+   * @default 53
+   */
+  weeks?: number;
+  /**
+   * Last day of the calendar. When rendering on the server, always pass it:
+   * the server and the browser may be on different days.
+   * @default today
+   */
+  endDate?: string | Date;
+  /**
+   * First day of each column: 0 = Sunday, 1 = Monday.
+   * @default 0
+   */
+  weekStart?: 0 | 1;
+  /**
+   * How counts map to the five color levels.
+   * @default 'quantile'
+   */
+  scale?: LevelScale;
+  /**
+   * Locale for dates and numbers. Fixed by default so server and client HTML match.
+   * @default 'en'
+   */
+  locale?: string;
+  /**
+   * Staggered entry animation. Turned off with `prefers-reduced-motion`.
+   * @default false
+   */
+  animate?: boolean;
+  /**
+   * Show the Less–More legend.
+   * @default true
+   */
+  showLegend?: boolean;
+  /**
+   * Show the header with the total.
+   * @default true
+   */
+  showTotal?: boolean;
+  /**
+   * Replaces the whole header text.
+   * @default '{total} contributions in the last year'
+   */
+  title?: ReactNode;
+  /**
+   * Singular and plural of the unit being counted.
+   * @default ['contribution', 'contributions']
+   */
+  unit?: readonly [string, string];
+  /**
+   * Text after the total in the header. Can be a function of the weeks shown.
+   * @default 'in the last year' (52+ weeks), otherwise 'in the last {weeks} weeks'
+   */
+  periodLabel?: string | ((weeks: number) => string);
+  /**
+   * Labels at both ends of the legend.
+   * @default ['Less', 'More']
+   */
+  legendLabels?: readonly [string, string];
+  /** Called when a day is clicked, or with Enter or Space while it is focused. */
+  onDayClick?: (day: CalendarDay) => void;
+  /** Extra class name for the root element. */
+  className?: string;
+  /** Inline styles for the root element. Theme CSS variables can be overridden here. */
+  style?: CSSProperties;
+  /**
+   * Accessible name of the graph.
+   * @default a summary with the total and the date range
+   */
+  'aria-label'?: string;
+}
+/** Returns a function that maps a count to a level from 0 to 4 for the given counts and scale. */
+declare function makeLevelFn(counts: readonly number[], scale?: LevelScale): (n: number) => Level;
+/** Options of `buildCalendar`. They match the graph props of the same name. */
+interface CalendarOptions {
+  weeks?: number;
+  endDate?: string | Date;
+  weekStart?: 0 | 1;
+  scale?: LevelScale;
+  locale?: string;
+}
+/** Lays out days as a weeks × 7 grid with levels, totals and month labels. Dates are handled in UTC. */
+declare function buildCalendar(data: readonly ContributionDay[], opts?: CalendarOptions): Calendar;
+/** Keeps the last `n` weeks. Levels come from the full calendar, so cropping doesn't change colors. */
+declare function cropCalendar(cal: Calendar, n: number, locale?: string): Calendar;
+/** Totals and streaks of a list of days. */
+interface GraphStats {
+  total: number;
+  activeDays: number;
+  best: CalendarDay | null;
+  longestStreak: number;
+  currentStreak: number;
+}
+/** Total, active days, best day, longest streak and current streak. A current streak isn't broken by a quiet today. */
+declare function computeStats(days: readonly CalendarDay[]): GraphStats;
+/** Formats an ISO date with `Intl`, in UTC so the day never shifts. */
+declare function formatDate(iso: string, locale?: string, opts?: Intl.DateTimeFormatOptions): string;
+/** Shape of the generated activity. */
+type SampleProfile = 'steady' | 'burst' | 'weekend' | 'sparse';
+/** Available sample profiles with a short English label. */
+declare const sampleProfiles: Record<SampleProfile, string>;
+/** Deterministic sample data: the same seed always gives the same days. Useful for demos and tests. */
+declare function generateSampleData({ seed, profile, days, endDate }?: {
+  seed?: number;
+  profile?: SampleProfile;
+  days?: number;
+  endDate?: Date;
+}): ContributionDay[];
+/**
+ * GitHub GraphQL query for the contribution calendar. It needs a token even
+ * for public data, so run it on the server and never send the token to the browser.
+ */
+declare const GITHUB_CONTRIBUTIONS_QUERY = "\n  query ($login: String!, $from: DateTime, $to: DateTime) {\n    user(login: $login) {\n      contributionsCollection(from: $from, to: $to) {\n        contributionCalendar {\n          totalContributions\n          weeks { contributionDays { date contributionCount } }\n        }\n      }\n    }\n  }\n";
+/** Shape of the GraphQL response read by `fromGitHub`. */
+interface GitHubCalendarResponse {
+  data?: {
+    user?: {
+      contributionsCollection?: {
+        contributionCalendar?: {
+          weeks: {
+            contributionDays: {
+              date: string;
+              contributionCount: number;
+            }[];
+          }[];
+        };
+      };
+    } | null;
+  };
+}
+/** Converts a GitHub GraphQL response into `{ date, count }` days. */
+declare function fromGitHub(res: GitHubCalendarResponse): ContributionDay[];
+/**
+ * Fetches the last year of contributions from GitHub's GraphQL API. Server only (Node 18+, Deno, Bun, edge runtimes).
+ * A classic token with `read:user` includes private contributions.
+ */
+declare function fetchGitHubContributions(login: string, token: string): Promise<ContributionDay[]>;
+/** Converts GitLab's `{ "2026-03-01": 4 }` calendar into `{ date, count }` days. */
+declare function fromGitLab(json: Record<string, number>): ContributionDay[];
+/**
+ * Fetches a GitLab user's calendar. The endpoint is public but sends no CORS headers,
+ * so call it from the server or at build time. Pass `baseUrl` for self-hosted instances.
+ */
+declare function fetchGitLabContributions(username: string, baseUrl?: string): Promise<ContributionDay[]>;
+/** Counts occurrences per day: blog posts, workouts, local commits… Strings are sliced to the date; `Date` objects use the local date. */
+declare function fromDates(dates: readonly (string | Date)[]): ContributionDay[];
+/** Adds several sources day by day (for example GitHub plus GitLab), sorted by date. */
+declare function mergeSources(...sources: readonly ContributionDay[][]): ContributionDay[];
+export { ThemePalette as A, ContributionDay as C, GraphTheme as D, MonthLabel as E, themeNames as M, themeVars as N, LevelColors as O, themes as P, ColorMode as S, LevelScale as T, formatDate as _, fromDates as a, Calendar as b, mergeSources as c, sampleProfiles as d, CalendarOptions as f, cropCalendar as g, computeStats as h, fetchGitLabContributions as i, resolveTheme as j, ThemeName as k, SampleProfile as l, buildCalendar as m, GitHubCalendarResponse as n, fromGitHub as o, GraphStats as p, fetchGitHubContributions as r, fromGitLab as s, GITHUB_CONTRIBUTIONS_QUERY as t, generateSampleData as u, makeLevelFn as v, Level as w, CalendarDay as x, BaseGraphProps as y };