@matthitachi/react-heatmap 1.0.0

package/Heatmap.tsx

@@ -0,0 +1,378 @@
+import React, { useMemo, useState } from 'react';
+import {
+  HeatmapProps,
+  HeatmapValue,
+  ProcessedWeekData,
+  ColorScale,
+} from './types';
+import styles from './styles.module.scss';
+
+// Default color scale (GitHub-style greens)
+const DEFAULT_COLOR_SCALE: ColorScale = {
+  0: '#ebedf0',
+  2: '#9be9a8',
+  5: '#40c463',
+  10: '#30a14e',
+  20: '#216e39',
+};
+
+const DEFAULT_MONTH_LABELS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const DEFAULT_WEEKDAY_LABELS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+/**
+ * Heatmap - A flexible, customizable calendar heatmap component
+ *
+ * @example
+ * ```tsx
+ * <Heatmap
+ *   values={[{ date: '2024-01-01', count: 5 }, { date: '2024-01-02', count: 12 }]}
+ *   startDate="2024-01-01"
+ *   endDate="2024-12-31"
+ *   showMonthLabels
+ *   showWeekdayLabels
+ * />
+ * ```
+ */
+export const Heatmap: React.FC<HeatmapProps> = ({
+  values,
+  startDate,
+  endDate,
+  showMonthLabels = true,
+  showWeekdayLabels = true,
+  monthPlacement = 'top',
+  weekStart = 0,
+  showLegend = true,
+  emptyMessage = 'No data available for the selected period.',
+  cellSize = 12,
+  cellGap = 3,
+  cellRadius = 2,
+  colorScale = DEFAULT_COLOR_SCALE,
+  surface = 'light',
+  className,
+  classNames = {},
+  style,
+  styles: customStyles = {},
+  tooltipFormatter,
+  onClick,
+  onMouseOver,
+  onMouseLeave,
+  monthLabels = DEFAULT_MONTH_LABELS,
+  weekdayLabels = DEFAULT_WEEKDAY_LABELS,
+}) => {
+  const [hoveredCell, setHoveredCell] = useState<{
+    value: HeatmapValue;
+    x: number;
+    y: number;
+  } | null>(null);
+
+  // Get color based on count and color scale
+  const getColor = (count: number, maxCount: number): string => {
+    if (count === 0) return colorScale[0] || DEFAULT_COLOR_SCALE[0];
+
+    const thresholds = Object.keys(colorScale)
+      .map(Number)
+      .sort((a, b) => b - a);
+
+    for (const threshold of thresholds) {
+      if (count >= threshold) {
+        return colorScale[threshold];
+      }
+    }
+
+    return colorScale[0] || DEFAULT_COLOR_SCALE[0];
+  };
+
+  // Process data into weeks
+  const { weeks, maxCount } = useMemo(() => {
+    if (!values || values.length === 0) {
+      return { weeks: [], maxCount: 0 };
+    }
+
+    // Find max count for color scaling
+    const max = Math.max(...values.map((v) => v.count));
+
+    // Create a map of dates to counts
+    const dateMap = new Map(values.map((v) => [v.date, v.count]));
+
+    // Parse start and end dates
+    const minDate = new Date(startDate);
+    const maxDate = new Date(endDate);
+
+    // Adjust to week boundaries based on weekStart
+    const startWeekDate = new Date(minDate);
+    const dayOffset = (startWeekDate.getDay() - weekStart + 7) % 7;
+    startWeekDate.setDate(startWeekDate.getDate() - dayOffset);
+
+    const endWeekDate = new Date(maxDate);
+    const endDayOffset = (6 - (endWeekDate.getDay() - weekStart + 7) % 7);
+    endWeekDate.setDate(endWeekDate.getDate() + endDayOffset);
+
+    // Generate all weeks
+    const weeksData: ProcessedWeekData[][] = [];
+    let currentWeek: ProcessedWeekData[] = [];
+    const currentDate = new Date(startWeekDate);
+
+    while (currentDate <= endWeekDate) {
+      const dateStr = currentDate.toISOString().split('T')[0];
+      const mapValue = dateMap.get(dateStr);
+      const count: number = typeof mapValue === 'number' ? mapValue : 0;
+
+      currentWeek.push({
+        date: new Date(currentDate),
+        count,
+        dateStr,
+      });
+
+      if (currentWeek.length === 7) {
+        weeksData.push(currentWeek);
+        currentWeek = [];
+      }
+
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+
+    if (currentWeek.length > 0) {
+      weeksData.push(currentWeek);
+    }
+
+    return { weeks: weeksData, maxCount: max };
+  }, [values, startDate, endDate, weekStart]);
+
+  // Calculate month positions for labels
+  const monthPositions = useMemo(() => {
+    const positions: { month: string; left: number }[] = [];
+    let lastMonth = -1;
+
+    weeks.forEach((week, weekIndex) => {
+      const firstDay = week[0];
+      const month = firstDay.date.getMonth();
+
+      if (month !== lastMonth) {
+        // Skip the first month label if it's a partial week at the beginning
+        if (weekIndex === 0) {
+          const daysInCurrentMonth = week.filter((day) => day.date.getMonth() === month).length;
+          if (daysInCurrentMonth < 4) {
+            lastMonth = month;
+            return;
+          }
+        }
+
+        positions.push({
+          month: monthLabels[month],
+          left: weekIndex * (cellSize + cellGap),
+        });
+        lastMonth = month;
+      }
+    });
+
+    return positions;
+  }, [weeks, monthLabels, cellSize, cellGap]);
+
+
+  // Default tooltip formatter
+  const defaultTooltipFormatter = (value: HeatmapValue): string => {
+    const count = value.count;
+    const label = count === 1 ? 'activity' : 'activities';
+    return `${count} ${label} on ${value.date}`;
+  };
+
+  const formatTooltip = tooltipFormatter || defaultTooltipFormatter;
+
+  // Handle cell interactions
+  const handleCellMouseEnter = (day: ProcessedWeekData, event: React.MouseEvent<HTMLDivElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    const value: HeatmapValue = { date: day.dateStr, count: day.count };
+
+    setHoveredCell({
+      value,
+      x: rect.left + rect.width / 2,
+      y: rect.top,
+    });
+
+    if (onMouseOver) {
+      onMouseOver(value, event);
+    }
+  };
+
+  const handleCellMouseLeave = (day: ProcessedWeekData, event: React.MouseEvent<HTMLDivElement>) => {
+    setHoveredCell(null);
+
+    if (onMouseLeave) {
+      const value: HeatmapValue = { date: day.dateStr, count: day.count };
+      onMouseLeave(null, event);
+    }
+  };
+
+  const handleCellClick = (day: ProcessedWeekData, event: React.MouseEvent<HTMLDivElement>) => {
+    if (onClick) {
+      const value: HeatmapValue = { date: day.dateStr, count: day.count };
+      onClick(value, event);
+    }
+  };
+
+  // Empty state
+  if (!values || values.length === 0) {
+    return (
+      <div
+        className={`${styles.heatmapEmptyState} ${styles[surface]} ${classNames.emptyState || ''} ${className || ''}`}
+        style={{ ...customStyles.emptyState, ...style }}
+      >
+        <p>{emptyMessage}</p>
+      </div>
+    );
+  }
+
+  // Get color scale values for legend
+  const colorScaleValues = Object.keys(colorScale)
+    .map(Number)
+    .sort((a, b) => a - b);
+
+  const legendColors = colorScaleValues.map((threshold) => colorScale[threshold]);
+
+  return (
+    <div
+      className={`${styles.heatmapContainer} ${styles[surface]} ${classNames.container || ''} ${className || ''}`}
+      style={{ ...customStyles.container, ...style }}
+    >
+      <div
+        className={`${styles.heatmapWrapper} ${classNames.wrapper || ''}`}
+        style={customStyles.wrapper}
+      >
+        <div
+          className={`${styles.heatmap} ${classNames.heatmap || ''}`}
+          style={{
+            paddingTop: showMonthLabels && monthPlacement === 'top' ? 20 : 0,
+            paddingBottom: showMonthLabels && monthPlacement === 'bottom' ? 20 : 0,
+            ...customStyles.heatmap,
+          }}
+        >
+          {/* Month labels */}
+          {showMonthLabels && (
+            <div
+              className={`${styles.monthLabels} ${styles[`monthLabels-${monthPlacement}`]} ${classNames.monthLabels || ''}`}
+              style={{
+                [monthPlacement]: 0,
+                left: showWeekdayLabels ? 50 : 0,
+                ...customStyles.monthLabels,
+              }}
+            >
+              {monthPositions.map((pos, index) => (
+                <div
+                  key={index}
+                  className={`${styles.monthLabel} ${classNames.monthLabel || ''}`}
+                  style={{ left: pos.left, ...customStyles.monthLabel }}
+                >
+                  {pos.month}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Weekday labels */}
+          {showWeekdayLabels && (
+            <div
+              className={`${styles.weekdayLabels} ${classNames.weekdayLabels || ''}`}
+              style={customStyles.weekdayLabels}
+            >
+              {weekdayLabels.map((day, i) => {
+                // Adjust index based on weekStart
+                const adjustedIndex = (i + weekStart) % 7;
+                return (
+                  <div
+                    key={day}
+                    className={`${styles.weekdayLabel} ${classNames.weekdayLabel || ''}`}
+                    style={{
+                      height: cellSize,
+                      lineHeight: `${cellSize}px`,
+                      ...customStyles.weekdayLabel,
+                    }}
+                  >
+                    {i % 2 === 1 ? weekdayLabels[adjustedIndex] : ''}
+                  </div>
+                );
+              })}
+            </div>
+          )}
+
+          {/* Heatmap grid */}
+          <div
+            className={`${styles.grid} ${classNames.grid || ''}`}
+            style={{ gap: cellGap, ...customStyles.grid }}
+          >
+            {weeks.map((week, weekIndex) => (
+              <div
+                key={weekIndex}
+                className={`${styles.week} ${classNames.week || ''}`}
+                style={{ gap: cellGap, ...customStyles.week }}
+              >
+                {week.map((day, dayIndex) => {
+                  const color = getColor(day.count, maxCount);
+                  const isActive = day.count > 0;
+
+                  return (
+                    <div
+                      key={`${weekIndex}-${dayIndex}`}
+                      className={`${styles.cell} ${isActive ? styles.cellActive : styles.cellEmpty} ${
+                        classNames.cell || ''
+                      } ${isActive ? classNames.cellActive || '' : classNames.cellEmpty || ''}`}
+                      style={{
+                        backgroundColor: color,
+                        width: cellSize,
+                        height: cellSize,
+                        borderRadius: cellRadius,
+                        marginBottom: cellGap,
+                        cursor: onClick ? 'pointer' : 'default',
+                        ...customStyles.cell,
+                      }}
+                      onMouseEnter={(e) => handleCellMouseEnter(day, e)}
+                      onMouseLeave={(e) => handleCellMouseLeave(day, e)}
+                      onClick={(e) => handleCellClick(day, e)}
+                    />
+                  );
+                })}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* Tooltip */}
+      {hoveredCell && (
+        <div
+          className={`${styles.tooltip} ${classNames.tooltip || ''}`}
+          style={{
+            left: hoveredCell.x,
+            top: hoveredCell.y - 10,
+            ...customStyles.tooltip,
+          }}
+        >
+          {formatTooltip(hoveredCell.value)}
+        </div>
+      )}
+
+      {/* Legend */}
+      {showLegend && (
+        <div
+          className={`${styles.legend} ${classNames.legend || ''}`}
+          style={customStyles.legend}
+        >
+          <span>Less</span>
+          <div className={`${styles.legendColors} ${classNames.legendColors || ''}`}>
+            {legendColors.map((color, index) => (
+              <span
+                key={index}
+                className={`${styles.legendBox} ${classNames.legendBox || ''}`}
+                style={{ backgroundColor: color }}
+              />
+            ))}
+          </div>
+          <span>More</span>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default Heatmap;
+
+

package/README.md

@@ -0,0 +1,342 @@
+# Heatmap Component
+
+A flexible, customizable calendar heatmap component for React, inspired by GitHub's contribution graph.
+
+## Features
+
+- 📅 **Flexible Date Ranges** - Display any date range with automatic week alignment
+- 🎨 **Customizable Colors** - Define your own color scales and thresholds
+- 🌓 **Light/Dark Mode** - Built-in theme support
+- 📱 **Responsive** - Horizontal scrolling for large date ranges
+- 🎯 **Interactive** - Click and hover handlers for cells
+- 🔧 **Highly Customizable** - Override styles and classes for any element
+- 📊 **Smart Labels** - Automatic month label positioning with overlap prevention
+- 🌍 **Week Start Options** - Start weeks on any day (Sunday, Monday, etc.)
+- 💡 **TypeScript** - Full TypeScript support with exported types
+
+## Installation
+
+```bash
+# If publishing as npm package
+npm install @your-org/react-heatmap
+
+# Or copy the component files to your project
+cp -r components/common/Heatmap /your-project/components/
+```
+
+## Basic Usage
+
+```tsx
+import { Heatmap } from '@/components/common/Heatmap';
+
+function MyComponent() {
+  const data = [
+    { date: '2024-01-01', count: 5 },
+    { date: '2024-01-02', count: 12 },
+    { date: '2024-01-03', count: 0 },
+    // ... more data
+  ];
+
+  return (
+    <Heatmap
+      values={data}
+      startDate="2024-01-01"
+      endDate="2024-12-31"
+    />
+  );
+}
+```
+
+## Props API
+
+### Data Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `values` | `HeatmapValue[]` | ✅ | - | Array of `{ date: string, count: number }` objects |
+| `startDate` | `string` | ✅ | - | Start date in ISO format (YYYY-MM-DD) |
+| `endDate` | `string` | ✅ | - | End date in ISO format (YYYY-MM-DD) |
+
+### Display Options
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `showMonthLabels` | `boolean` | ❌ | `true` | Show month labels |
+| `showWeekdayLabels` | `boolean` | ❌ | `true` | Show weekday labels |
+| `monthPlacement` | `'top' \| 'bottom'` | ❌ | `'top'` | Position of month labels |
+| `weekStart` | `0-6` | ❌ | `0` | Starting day of week (0=Sunday, 1=Monday, etc.) |
+| `showLegend` | `boolean` | ❌ | `true` | Show color legend |
+| `emptyMessage` | `string` | ❌ | `'No data available...'` | Message shown when no data |
+
+### Sizing Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `cellSize` | `number` | ❌ | `12` | Size of each cell in pixels |
+| `cellGap` | `number` | ❌ | `3` | Gap between cells in pixels |
+| `cellRadius` | `number` | ❌ | `2` | Border radius for cells in pixels |
+
+### Color Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `colorScale` | `ColorScale` | ❌ | GitHub greens | Color thresholds object |
+| `surface` | `'light' \| 'dark'` | ❌ | `'light'` | Theme mode |
+
+### Styling Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `className` | `string` | ❌ | - | Custom class for container |
+| `classNames` | `HeatmapClassNames` | ❌ | - | Override classes for elements |
+| `style` | `CSSProperties` | ❌ | - | Inline styles for container |
+| `styles` | `HeatmapStyles` | ❌ | - | Override styles for elements |
+
+### Interaction Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `tooltipFormatter` | `(value) => string` | ❌ | Default formatter | Custom tooltip content |
+| `onClick` | `(value, event) => void` | ❌ | - | Cell click handler |
+| `onMouseOver` | `(value, event) => void` | ❌ | - | Cell hover handler |
+| `onMouseLeave` | `(value, event) => void` | ❌ | - | Cell leave handler |
+
+### Label Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `monthLabels` | `string[]` | ❌ | `['Jan', 'Feb', ...]` | Custom month labels |
+| `weekdayLabels` | `string[]` | ❌ | `['Sun', 'Mon', ...]` | Custom weekday labels |
+
+## Advanced Examples
+
+### Custom Color Scale
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  colorScale={{
+    0: '#f0f0f0',
+    5: '#c6e48b',
+    10: '#7bc96f',
+    15: '#239a3b',
+    20: '#196127',
+  }}
+/>
+```
+
+### Week Starting on Monday
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  weekStart={1}
+  weekdayLabels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
+/>
+```
+
+### Custom Tooltip
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  tooltipFormatter={(value) =>
+    `${value.count} contributions on ${new Date(value.date).toLocaleDateString()}`
+  }
+/>
+```
+
+### Dark Mode
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  surface="dark"
+/>
+```
+
+### Month Labels at Bottom
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  monthPlacement="bottom"
+/>
+```
+
+### Minimal Heatmap (No Labels or Legend)
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  showMonthLabels={false}
+  showWeekdayLabels={false}
+  showLegend={false}
+/>
+```
+
+## TypeScript Types
+
+```typescript
+interface HeatmapValue {
+  date: string;  // ISO format: YYYY-MM-DD
+  count: number;
+}
+
+interface ColorScale {
+  [threshold: number]: string;
+}
+
+type TooltipFormatter = (value: HeatmapValue) => string;
+type CellClickHandler = (value: HeatmapValue, event: MouseEvent<HTMLDivElement>) => void;
+type CellHoverHandler = (value: HeatmapValue | null, event: MouseEvent<HTMLDivElement>) => void;
+```
+
+## Customization Guide
+
+### Override Individual Element Classes
+
+The `classNames` prop allows you to override classes for specific elements:
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  classNames={{
+    container: 'my-container',
+    cell: 'my-cell',
+    cellActive: 'my-active-cell',
+    cellEmpty: 'my-empty-cell',
+    tooltip: 'my-tooltip',
+    legend: 'my-legend',
+    monthLabel: 'my-month-label',
+    weekdayLabel: 'my-weekday-label',
+  }}
+/>
+```
+
+### Override Individual Element Styles
+
+The `styles` prop allows you to override inline styles:
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  styles={{
+    container: { backgroundColor: '#f5f5f5', padding: '20px' },
+    cell: { borderRadius: '4px' },
+    tooltip: { fontSize: '14px', padding: '8px 12px' },
+    legend: { justifyContent: 'center' },
+  }}
+/>
+```
+
+## Default Color Scale
+
+The default color scale uses GitHub-style greens:
+
+```typescript
+{
+  0: '#ebedf0',   // Empty/no activity
+  2: '#9be9a8',   // Low activity
+  5: '#40c463',   // Medium activity
+  10: '#30a14e',  // High activity
+  20: '#216e39',  // Very high activity
+}
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Performance Considerations
+
+- The component efficiently handles large date ranges (multiple years)
+- Uses `useMemo` for expensive calculations
+- Horizontal scrolling for wide heatmaps
+- Optimized re-renders with proper dependency arrays
+
+## Accessibility
+
+- Semantic HTML structure
+- Keyboard navigation support (when click handlers are provided)
+- ARIA labels can be added via `classNames` and custom attributes
+- High contrast mode compatible
+
+## License
+
+MIT
+
+## Credits
+
+Inspired by:
+- [GitHub's contribution graph](https://github.com)
+- [react-calendar-heatmap](https://github.com/kevinsqi/react-calendar-heatmap)
+- [@uiw/react-heat-map](https://github.com/uiwjs/react-heat-map)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Changelog
+
+### v1.0.0
+- Initial release
+- Full TypeScript support
+- Customizable color scales
+- Light/Dark mode
+- Interactive tooltips
+- Click and hover handlers
+- Smart month label positioning
+- Week start customization
+
+### Click Handler
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  onClick={(value, event) => {
+    console.log(`Clicked on ${value.date} with ${value.count} activities`);
+  }}
+/>
+```
+
+### Custom Styling
+
+```tsx
+<Heatmap
+  values={data}
+  startDate="2024-01-01"
+  endDate="2024-12-31"
+  className="my-custom-heatmap"
+  classNames={{
+    cell: 'custom-cell',
+    tooltip: 'custom-tooltip',
+  }}
+  styles={{
+    container: { padding: '24px' },
+    cell: { borderRadius: '50%' },
+  }}
+/>
+```
+

package/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Heatmap Component Package
+ * 
+ * A flexible, customizable calendar heatmap component for React
+ * Inspired by GitHub's contribution graph
+ * 
+ * @example
+ * ```tsx
+ * import { Heatmap } from '@/components/common/Heatmap';
+ * 
+ * function MyComponent() {
+ *   return (
+ *     <Heatmap
+ *       values={[
+ *         { date: '2024-01-01', count: 5 },
+ *         { date: '2024-01-02', count: 12 }
+ *       ]}
+ *       startDate="2024-01-01"
+ *       endDate="2024-12-31"
+ *       showMonthLabels
+ *       showWeekdayLabels
+ *       showLegend
+ *     />
+ *   );
+ * }
+ * ```
+ */
+
+export { Heatmap, default } from './Heatmap';
+export type {
+  HeatmapValue,
+  HeatmapProps,
+  HeatmapClassNames,
+  HeatmapStyles,
+  ColorScale,
+  TooltipFormatter,
+  CellClickHandler,
+  CellHoverHandler,
+  ProcessedWeekData,
+} from './types';
+

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@matthitachi/react-heatmap",
+  "version": "1.0.0",
+  "description": "A flexible, customizable calendar heatmap component for React, inspired by GitHub's contribution graph",
+  "main": "index.ts",
+  "types": "types.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "react",
+    "heatmap",
+    "calendar",
+    "contribution-graph",
+    "github",
+    "visualization",
+    "chart",
+    "typescript",
+    "component"
+  ],
+  "author": "Matthre Adiorho",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "typescript": "^5.0.0",
+    "sass": "^1.60.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/matthitachi/react-heatmap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/matthitachi/react-heatmap/issues"
+  },
+  "homepage": "https://github.com/matthitachi/react-heatmap#readme",
+  "files": [
+    "Heatmap.tsx",
+    "types.ts",
+    "styles.module.scss",
+    "index.ts",
+    "README.md"
+  ]
+}
+

package/styles.module.scss

@@ -0,0 +1,215 @@
+// Heatmap Component Styles
+// Framework-agnostic, reusable styles
+
+.heatmapContainer {
+  width: 100%;
+  padding: 16px;
+  border-radius: 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  position: relative;
+
+  // Light mode (default)
+  &.light {
+    background-color: #ffffff;
+
+    .weekdayLabel,
+    .monthLabel {
+      color: #666;
+    }
+
+    .cell {
+      border: 1px solid rgba(27, 31, 35, 0.06);
+
+      &:hover {
+        border-color: rgba(27, 31, 35, 0.15);
+        transform: scale(1.1);
+      }
+    }
+
+    .legend {
+      color: #666;
+    }
+
+    .legendBox {
+      border: 1px solid rgba(27, 31, 35, 0.06);
+    }
+  }
+
+  // Dark mode
+  &.dark {
+    background-color: rgba(225, 223, 246, 0.15);
+
+    .weekdayLabel,
+    .monthLabel {
+      color: rgba(255, 255, 255, 0.5);
+    }
+
+    .cell {
+      border: 1px solid rgba(255, 255, 255, 0.1);
+
+      &:hover {
+        border-color: rgba(255, 255, 255, 0.3);
+        transform: scale(1.1);
+      }
+    }
+
+    .legend {
+      color: rgba(255, 255, 255, 0.7);
+    }
+
+    .legendBox {
+      border: 1px solid rgba(255, 255, 255, 0.2);
+    }
+
+    .tooltip {
+      background-color: rgba(0, 0, 0, 0.95);
+      border: 1px solid rgba(255, 255, 255, 0.2);
+    }
+  }
+}
+
+.heatmapWrapper {
+  width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  padding: 10px 0;
+}
+
+.heatmap {
+  display: flex;
+  gap: 10px;
+  min-width: fit-content;
+  position: relative;
+}
+
+.monthLabels {
+  position: absolute;
+  left: 50px;
+  height: 18px;
+  display: flex;
+  font-size: 11px;
+
+  &.monthLabels-top {
+    top: 0;
+  }
+
+  &.monthLabels-bottom {
+    bottom: 0;
+  }
+}
+
+.monthLabel {
+  position: absolute;
+  white-space: nowrap;
+}
+
+.weekdayLabels {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  padding-right: 5px;
+}
+
+.weekdayLabel {
+  font-size: 10px;
+  text-align: right;
+  padding-right: 5px;
+}
+
+.grid {
+  display: flex;
+  gap: 3px;
+}
+
+.week {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+.cell {
+  border-radius: 2px;
+  transition: all 0.2s ease;
+
+  &.cellActive {
+    cursor: pointer;
+  }
+
+  &.cellEmpty {
+    opacity: 0.5;
+  }
+}
+
+.tooltip {
+  position: fixed;
+  transform: translate(-50%, -100%);
+  background-color: rgba(0, 0, 0, 0.9);
+  color: white;
+  padding: 6px 10px;
+  border-radius: 4px;
+  font-size: 12px;
+  white-space: nowrap;
+  pointer-events: none;
+  z-index: 1000;
+
+  &::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    border: 5px solid transparent;
+    border-top-color: rgba(0, 0, 0, 0.9);
+  }
+}
+
+.legend {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 4px;
+  font-size: 12px;
+  margin-top: 8px;
+}
+
+.legendColors {
+  display: flex;
+  gap: 2px;
+  margin: 0 4px;
+}
+
+.legendBox {
+  width: 12px;
+  height: 12px;
+  border-radius: 2px;
+  display: inline-block;
+}
+
+.heatmapEmptyState {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 200px;
+  font-size: 14px;
+  padding: 20px;
+  border-radius: 8px;
+
+  p {
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans',
+      'Droid Sans', 'Helvetica Neue', sans-serif;
+  }
+
+  &.light {
+    background-color: #ffffff;
+    color: #666;
+  }
+
+  &.dark {
+    background-color: rgba(225, 223, 246, 0.15);
+    color: rgba(255, 255, 255, 0.6);
+  }
+}
+

package/types.ts

@@ -0,0 +1,153 @@
+import { CSSProperties, MouseEvent } from 'react';
+
+/**
+ * Data point for a single day in the heatmap
+ */
+export interface HeatmapValue {
+  /** Date in ISO format (YYYY-MM-DD) */
+  date: string;
+  /** Activity count for this date */
+  count: number;
+}
+
+/**
+ * Color scale configuration
+ * Maps threshold values to colors
+ */
+export interface ColorScale {
+  [threshold: number]: string;
+}
+
+/**
+ * Custom class names for heatmap elements
+ */
+export interface HeatmapClassNames {
+  container?: string;
+  wrapper?: string;
+  heatmap?: string;
+  monthLabels?: string;
+  monthLabel?: string;
+  weekdayLabels?: string;
+  weekdayLabel?: string;
+  grid?: string;
+  week?: string;
+  cell?: string;
+  cellEmpty?: string;
+  cellActive?: string;
+  tooltip?: string;
+  legend?: string;
+  legendColors?: string;
+  legendBox?: string;
+  emptyState?: string;
+}
+
+/**
+ * Custom inline styles for heatmap elements
+ */
+export interface HeatmapStyles {
+  container?: CSSProperties;
+  wrapper?: CSSProperties;
+  heatmap?: CSSProperties;
+  monthLabels?: CSSProperties;
+  monthLabel?: CSSProperties;
+  weekdayLabels?: CSSProperties;
+  weekdayLabel?: CSSProperties;
+  grid?: CSSProperties;
+  week?: CSSProperties;
+  cell?: CSSProperties;
+  tooltip?: CSSProperties;
+  legend?: CSSProperties;
+  emptyState?: CSSProperties;
+}
+
+/**
+ * Tooltip formatter function
+ */
+export type TooltipFormatter = (value: HeatmapValue) => string;
+
+/**
+ * Cell click handler
+ */
+export type CellClickHandler = (value: HeatmapValue, event: MouseEvent<HTMLDivElement>) => void;
+
+/**
+ * Cell hover handlers
+ */
+export type CellHoverHandler = (value: HeatmapValue | null, event: MouseEvent<HTMLDivElement>) => void;
+
+/**
+ * Main props for the Heatmap component
+ */
+export interface HeatmapProps {
+  // Data props
+  /** Array of data points with date and count */
+  values: HeatmapValue[];
+  /** Start date for the heatmap (ISO format YYYY-MM-DD) */
+  startDate: string;
+  /** End date for the heatmap (ISO format YYYY-MM-DD) */
+  endDate: string;
+
+  // Display options
+  /** Show month labels at top or bottom (default: true) */
+  showMonthLabels?: boolean;
+  /** Show weekday labels on the left (default: true) */
+  showWeekdayLabels?: boolean;
+  /** Position of month labels (default: 'top') */
+  monthPlacement?: 'top' | 'bottom';
+  /** Starting day of the week: 0 (Sunday) to 6 (Saturday) (default: 0) */
+  weekStart?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Show legend (default: true) */
+  showLegend?: boolean;
+  /** Custom empty state message */
+  emptyMessage?: string;
+
+  // Sizing props
+  /** Size of each cell in pixels (default: 12) */
+  cellSize?: number;
+  /** Gap between cells in pixels (default: 3) */
+  cellGap?: number;
+  /** Border radius for cells in pixels (default: 2) */
+  cellRadius?: number;
+
+  // Color props
+  /** Color scale with thresholds (default: GitHub-style greens) */
+  colorScale?: ColorScale;
+  /** Theme mode (default: 'light') */
+  surface?: 'light' | 'dark';
+
+  // Styling props
+  /** Custom class name for the container */
+  className?: string;
+  /** Custom class names for individual elements */
+  classNames?: HeatmapClassNames;
+  /** Inline styles for the container */
+  style?: CSSProperties;
+  /** Inline styles for individual elements */
+  styles?: HeatmapStyles;
+
+  // Interaction props
+  /** Custom tooltip formatter function */
+  tooltipFormatter?: TooltipFormatter;
+  /** Click handler for cells */
+  onClick?: CellClickHandler;
+  /** Mouse enter handler for cells */
+  onMouseOver?: CellHoverHandler;
+  /** Mouse leave handler for cells */
+  onMouseLeave?: CellHoverHandler;
+
+  // Labels
+  /** Custom month labels (default: ['Jan', 'Feb', ...]) */
+  monthLabels?: string[];
+  /** Custom weekday labels (default: ['Sun', 'Mon', ...]) */
+  weekdayLabels?: string[];
+}
+
+/**
+ * Internal processed data structure
+ */
+export interface ProcessedWeekData {
+  date: Date;
+  count: number;
+  dateStr: string;
+}
+