@riishabh/react-calender-heatmap 4.1.1 โ 5.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +129 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,149 @@
|
|
|
1
|
-
#
|
|
1
|
+
# React Calendar Heatmap
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@riishabh/react-calender-heatmap` is a lightweight React component that renders a contribution-style calendar heatmap. It ships with sensible defaults, supports custom day states, and now works seamlessly in both React 18 and React 19 applications.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Highlights
|
|
6
|
+
- โ
**React 18 & 19 support** with strict TypeScript typings
|
|
7
|
+
- ๐งฉ **Plug-and-play component** โ no context or provider setup required
|
|
8
|
+
- ๐จ **Customizable color palette** for different attendance or productivity states
|
|
9
|
+
- ๐งช **Storybook & Testing Library** integration for rapid UI iteration
|
|
6
10
|
|
|
7
|
-
##
|
|
11
|
+
## Installation
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
+
```bash
|
|
14
|
+
npm install @riishabh/react-calender-heatmap
|
|
15
|
+
# or
|
|
16
|
+
yarn add @riishabh/react-calender-heatmap
|
|
17
|
+
# or
|
|
18
|
+
pnpm add @riishabh/react-calender-heatmap
|
|
19
|
+
```
|
|
13
20
|
|
|
14
|
-
|
|
21
|
+
### Peer dependencies
|
|
22
|
+
- `react`: `^18.2.0 || ^19.0.0`
|
|
23
|
+
- `react-dom`: match your React version
|
|
24
|
+
|
|
25
|
+
## Quick Start
|
|
15
26
|
|
|
16
27
|
```tsx
|
|
17
|
-
import TileChart from '
|
|
28
|
+
import { TileChart } from '@riishabh/react-calender-heatmap';
|
|
18
29
|
|
|
19
30
|
const data = [
|
|
20
|
-
{ date: '
|
|
21
|
-
{ date: '
|
|
22
|
-
|
|
31
|
+
{ date: '2024-01-01', status: 'success' },
|
|
32
|
+
{ date: '2024-01-02', status: 'warning' },
|
|
33
|
+
{ date: '2024-01-03', status: 'holiday' },
|
|
23
34
|
];
|
|
24
35
|
|
|
25
|
-
function
|
|
36
|
+
export function AttendanceHeatmap() {
|
|
26
37
|
return (
|
|
27
38
|
<TileChart
|
|
28
39
|
data={data}
|
|
29
40
|
range={6}
|
|
30
|
-
onTileHover={(date, status) => console.log(date, status)}
|
|
31
41
|
tileText="Day"
|
|
42
|
+
onTileHover={(label, status) => {
|
|
43
|
+
if (status) {
|
|
44
|
+
console.log(`${label} โ ${status}`);
|
|
45
|
+
}
|
|
46
|
+
}}
|
|
32
47
|
/>
|
|
33
48
|
);
|
|
34
49
|
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Importing the package automatically injects the default stylesheet, so the heatmap is ready to render without additional configuration.
|
|
53
|
+
|
|
54
|
+
## Data shape
|
|
55
|
+
|
|
56
|
+
Each entry in the `data` array corresponds to a day.
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
type TileState =
|
|
60
|
+
| 'success'
|
|
61
|
+
| 'warning'
|
|
62
|
+
| 'alert'
|
|
63
|
+
| 'holiday'
|
|
64
|
+
| 'weekend'
|
|
65
|
+
| 'fullDayLeave'
|
|
66
|
+
| 'halfDayLeave';
|
|
67
|
+
|
|
68
|
+
interface TileDataPoint {
|
|
69
|
+
date: string; // any ISO-8601 string parsable by new Date()
|
|
70
|
+
status?: TileState;
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Component props
|
|
75
|
+
|
|
76
|
+
| Prop | Type | Default | Description |
|
|
77
|
+
|---------------|----------------------------------------------------------------------------------------|---------|---------------------------------------------------------------------------------------------------------|
|
|
78
|
+
| `data` | `TileDataPoint[]` | โ | Source data for the heatmap. Dates should be parseable by the browser's `Date` constructor. |
|
|
79
|
+
| `range` | `3 \| 6 \| 12` | `6` | Number of months (backwards from the current month) to render. |
|
|
80
|
+
| `onTileHover` | `(label: string, status?: TileState) => void` | โ | Callback fired after a tile has been hovered long enough for the tooltip to appear. Empty string clears.|
|
|
81
|
+
| `tileText` | `string` | โ | Optional static string shown in the tooltip instead of the generated date string. |
|
|
82
|
+
|
|
83
|
+
## Visual states
|
|
84
|
+
|
|
85
|
+
Use one of the built-in `status` values to map data to colors. Override the classes below to match your design system.
|
|
86
|
+
|
|
87
|
+
| Status | Class | Default styling (excerpt) |
|
|
88
|
+
|-----------------|-------------------|--------------------------------------------------------|
|
|
89
|
+
| `success` | `.bg-success` | green background, subtle border |
|
|
90
|
+
| `warning` | `.bg-warning` | amber background |
|
|
91
|
+
| `alert` | `.bg-alert` | red background |
|
|
92
|
+
| `holiday` | `.bg-holiday` | blue background |
|
|
93
|
+
| `weekend` | `.bg-weekend` | lilac background |
|
|
94
|
+
| `fullDayLeave` | `.bg-fullDayLeave`| burnt orange background |
|
|
95
|
+
| `halfDayLeave` | `.bg-halfDayLeave`| magenta background |
|
|
96
|
+
| _unset_ | `.bg-default` | neutral gray background |
|
|
97
|
+
|
|
98
|
+
### Customizing the palette
|
|
99
|
+
|
|
100
|
+
Create a global stylesheet (or use CSS modules) to override the classes:
|
|
101
|
+
|
|
102
|
+
```css
|
|
103
|
+
:root {
|
|
104
|
+
--heatmap-success: #00a86b;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
.bg-success {
|
|
108
|
+
background-color: var(--heatmap-success);
|
|
109
|
+
border-color: rgba(0, 168, 107, 0.45);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Because the component injects its CSS at runtime, make sure your overrides load after the component (for example, in your app-level stylesheet).
|
|
114
|
+
|
|
115
|
+
## Tooltip & interactions
|
|
116
|
+
|
|
117
|
+
Tile hover events emit a human-friendly label (e.g. `3rd Jan 24`) and the resolved status. Use this to show additional UI (like side panels or analytics) or to hook into analytics events.
|
|
118
|
+
|
|
119
|
+
```tsx
|
|
120
|
+
<TileChart
|
|
121
|
+
data={data}
|
|
122
|
+
onTileHover={(label, status) => track('heatmap-hover', { label, status })}
|
|
123
|
+
/>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
## TypeScript support
|
|
127
|
+
|
|
128
|
+
All exports ship with `.d.ts` files generated from the source TypeScript. If you need to narrow the `status` union for your own domain, extend the provided `TileChartProps`:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import type { TileChartProps } from '@riishabh/react-calender-heatmap';
|
|
132
|
+
|
|
133
|
+
type CustomTileState = TileChartProps['data'][number]['status'] | 'remote';
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Development & contributing
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npm install # install dependencies
|
|
140
|
+
npm run storybook # launch interactive component docs at http://localhost:6006
|
|
141
|
+
npm run build # create the production-ready bundles in /dist
|
|
142
|
+
npm test # (optional) run Jest in watch mode
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Feel free to open issues or pull requests on [GitHub](https://github.com/badcaptain0001/react-calendar-heatmap) with feature ideas or fixes.
|
|
146
|
+
|
|
147
|
+
## License
|
|
35
148
|
|
|
36
|
-
|
|
149
|
+
MIT ยฉ Rishabh Sharma
|