contrib-graphs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francis Miguel Castillo Cruz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# contrib-graphs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Isometric contribution graph](https://raw.githubusercontent.com/ingfranciscastillo/contrib-graphs/main/docs/images/isometric-light.svg)
+
+Contribution graph components for React: GitHub-style activity heatmaps in seven designs (Classic, Dots, Isometric, Terminal, Radial, Skyline, Compact), with themes, light/dark mode, keyboard navigation and screen reader support.
+
+```bash
+npm install contrib-graphs
+```
+
+```tsx
+import { ClassicGraph } from 'contrib-graphs'
+import 'contrib-graphs/styles.css'
+
+const data = [
+  { date: '2026-11-10', count: 4 },
+  { date: '2026-11-11', count: 9 },
+]
+
+export function Activity() {
+  return <ClassicGraph data={data} theme="github" animate />
+}
+```
+
+Every component takes the same `{ date, count }[]` data. Adapters for GitHub and GitLab (`fromGitHub`, `fromGitLab`, `fetchGitHubContributions`, `fetchGitLabContributions`) and generic sources (`fromDates`, `mergeSources`) are included.
+
+Requires React 18 or later.
+
+## Next.js, Astro and server rendering
+
+- `contrib-graphs` exports the components and starts with `"use client"`, so you can render them straight from a Next.js Server Component.
+- `contrib-graphs/data` exports everything else (calendar helpers, themes, adapters, sample data) with no React dependency. Use it on the server, for example `fetchGitHubContributions` in a Server Component or an Astro page.
+- In Astro (with `@astrojs/react`), a graph without a `client:*` directive ships as static HTML with no JavaScript; add `client:visible` for tooltips and keyboard navigation. Functions can't be passed to islands, so wrap the graph in a React component to use `onDayClick`.
+- When rendering on the server, pass `endDate` (for real data, the last date in it): the server and the browser may be on different days. Dates and numbers default to the `en` locale on both sides.
+
+```tsx
+// app/page.tsx (Next.js)
+import { ClassicGraph } from 'contrib-graphs'
+import { fetchGitHubContributions } from 'contrib-graphs/data'
+
+export default async function Page() {
+  const data = await fetchGitHubContributions('your-username', process.env.GITHUB_TOKEN!)
+  return <ClassicGraph data={data} endDate={data.at(-1)?.date} />
+}
+```
+
+Tested with Next.js 16 (React 19) and Astro 6.
+
+Live gallery, playground and full API reference: [ingfranciscastillo.github.io/contrib-graphs](https://ingfranciscastillo.github.io/contrib-graphs/). Source and more designs: [github.com/ingfranciscastillo/contrib-graphs](https://github.com/ingfranciscastillo/contrib-graphs).
+
+## License
+
+MIT

package/dist/data-DptvXfjH.d.cts

@@ -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 };