@wello-dev/charts 0.0.0-stage → 1.0.4

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/LICENSE ADDED
@@ -0,0 +1,47 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wello-dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ --------------------------------------------------------------------------------
24
+
25
+ Portions of this package are derived from software under this licence:
26
+
27
+ MIT License
28
+
29
+ Copyright (c) 2021 Vitaly Rtishchev
30
+
31
+ Permission is hereby granted, free of charge, to any person obtaining a copy
32
+ of this software and associated documentation files (the "Software"), to deal
33
+ in the Software without restriction, including without limitation the rights
34
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
35
+ copies of the Software, and to permit persons to whom the Software is
36
+ furnished to do so, subject to the following conditions:
37
+
38
+ The above copyright notice and this permission notice shall be included in all
39
+ copies or substantial portions of the Software.
40
+
41
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
42
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
43
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
44
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
45
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
46
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
47
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,155 @@
1
- # Temporary Holding Version
1
+ # @wello-dev/charts
2
2
 
3
- 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.
3
+ React charts built on [recharts](https://recharts.org): **AreaChart, BarChart, LineChart, PieChart, DonutChart, RadialBarChart** and a calendar **Heatmap**.
4
+
5
+ - Simple prop names (`data`, `dataKey`, `series`, `withLegend`, `withTooltip`, `type`, `curveType`, …).
6
+ - Colors are optional: series and slices without `color` take the next `CHART_COLORS` entry (emerald, amber, violet, orange, …). Colors use Tailwind names: `'blue-600'`, `'blue-700'`, `'emerald'` (= 500), from 50 to 950. They resolve to `var(--color-blue-600, #2563eb)`, so a Tailwind v4 theme's own values are used and the default Tailwind hex is the fallback. Any CSS color or variable also works.
7
+ - Dashboard look: transparent (sits on your card, axis text and grid follow its text color), dark inverted tooltips, dashed grid, no axis lines, rounded bars, smooth 2px lines with dots, rounded donut slices that grow and glow on hover, 650ms animations.
8
+ - Every chart is rendered in a card by default, with theme-aware background and border, rounded corners, padding, and a subtle shadow.
9
+ - `loading` skeleton and `emptyLabel` state on every chart; right-to-left layout follows `dir="rtl"`.
10
+ - Light by default; dark inside `.dark` or `[data-theme="dark"]`.
11
+ - Ships with `"use client"` for the Next.js App Router.
12
+
13
+ ```bash
14
+ pnpm add @wello-dev/charts recharts
15
+ ```
16
+
17
+ Styles are included automatically: importing any chart adds them to the page, so there is no CSS file to import. `@wello-dev/charts/styles.css` is still exported if you prefer to load the stylesheet yourself (for example to control its order in your CSS). To change the default card appearance, override `.wello-chart` styles or use `classNames.root`.
18
+
19
+ ## Cartesian charts: Area, Bar, Line
20
+
21
+ ```tsx
22
+ import { AreaChart, BarChart, LineChart } from "@wello-dev/charts";
23
+
24
+ const data = [
25
+ { date: "Mar 22", Apples: 2890, Oranges: 2338 },
26
+ { date: "Mar 23", Apples: 2756, Oranges: 2103 },
27
+ ];
28
+
29
+ <AreaChart
30
+ h={300}
31
+ data={data}
32
+ dataKey="date"
33
+ type="stacked"
34
+ withLegend
35
+ valueFormatter={(value) => new Intl.NumberFormat("en-US").format(value)}
36
+ series={[
37
+ { name: "Apples", color: "indigo-600" },
38
+ { name: "Oranges", label: "Orange sales", color: "blue-600", strokeDasharray: "5 5" },
39
+ ]}
40
+ referenceLines={[{ y: 3000, label: "Target", color: "red-600" }]}
41
+ />;
42
+ ```
43
+
44
+ Shared props:
45
+
46
+ | Prop | Description |
47
+ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
48
+ | `data`, `dataKey`, `series` | Rows, the x-axis key, and `{ name, color, label?, yAxisId?, strokeDasharray? }[]` |
49
+ | `h`, `w` | Size (default `300` × `100%`) |
50
+ | `className`, `classNames` | Root class (backward-compatible) and per-part classes: `{ root, chart, legend }`; use `root` for card styling such as borders, padding, and shadows |
51
+ | `colors` | Palette for series without `color` (default `CHART_COLORS`) |
52
+ | `loading`, `emptyLabel` | Skeleton while loading; message when there is no data or every value is 0 (default `'No data'`) |
53
+ | `animationDuration` | Default `650`; `0` disables |
54
+ | `orientation` | `'horizontal'` (default) or `'vertical'` |
55
+ | `withLegend`, `legendProps` | Legend (`verticalAlign`, `align`, `highlightOnHover`); hovering an item dims the other series |
56
+ | `withTooltip`, `tooltipProps`, `tooltipAnimationDuration` | Tooltip (on by default); `tooltipProps` go to recharts `Tooltip` |
57
+ | `withXAxis`, `withYAxis`, `xAxisProps`, `yAxisProps`, `xAxisLabel`, `yAxisLabel` | Axes |
58
+ | `withRightYAxis`, `rightYAxisProps`, `rightYAxisLabel` | Right axis; bind series with `yAxisId: 'right'` |
59
+ | `gridAxis`, `gridProps`, `tickLine` (default `'none'`), `strokeDasharray`, `gridColor`, `textColor` | Grid and ticks |
60
+ | `unit`, `valueFormatter` | y-axis ticks and tooltip values |
61
+ | `referenceLines` | `{ x?, y?, label?, color?, strokeDasharray? }[]` |
62
+ | `children` | Extra recharts elements |
63
+
64
+ | Chart | Own props |
65
+ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
66
+ | `AreaChart` | `type`: `default` \| `stacked` \| `percent` \| `split`; `curveType`, `withGradient`, `fillOpacity`, `strokeWidth`, `withDots`, `dotProps`, `activeDotProps`, `connectNulls`, `withPointLabels`, `splitColors`, `splitOffset`, `areaChartProps`, `areaProps` |
67
+ | `BarChart` | `type`: `default` \| `stacked` \| `percent` \| `waterfall`; `fillOpacity`, `maxBarWidth`, `minBarSize`, `withBarValueLabel`, `valueLabelProps`, `getBarColor(value, series)`, `barChartProps`, `barProps` |
68
+ | `LineChart` | `type`: `default` \| `gradient` (with `gradientStops`); `curveType`, `strokeWidth`, `withDots`, `dotProps`, `activeDotProps`, `connectNulls`, `withPointLabels`, `lineChartProps`, `lineProps` |
69
+
70
+ Waterfall bars use the first series; rows with `standalone: true` start at 0 (totals) and `color` colors a single bar.
71
+
72
+ ## PieChart and DonutChart
73
+
74
+ ```tsx
75
+ import { DonutChart, PieChart } from "@wello-dev/charts";
76
+
77
+ const data = [
78
+ { name: "USA", value: 400, color: "indigo-600" },
79
+ { name: "India", value: 300, color: "yellow-600" },
80
+ ];
81
+
82
+ <PieChart data={data} withLabels labelsType="percent" withTooltip />
83
+ <DonutChart data={data} chartLabel="700 users" thickness={30} paddingAngle={4} />
84
+ ```
85
+
86
+ | Prop | Description |
87
+ | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
88
+ | `size` | Diameter (default `160`) |
89
+ | `withLabels`, `labelsType`, `withLabelsLine`, `labelColor` | Labels: `'value'` or `'percent'` |
90
+ | `labelsPosition` | Pie only: `'outside'` (default) or `'inside'` |
91
+ | `thickness`, `chartLabel`, `chartSubLabel`, `emptyRing` | Donut only: ring width (about a quarter of the radius), large center value, small label under it, and a muted ring instead of the empty state when every value is 0 |
92
+ | `colors`, `cornerRadius` | Palette for slices without `color`; slice corner radius (default `6`) |
93
+ | `loading`, `emptyLabel`, `animationDuration` | Same as the cartesian charts |
94
+ | `paddingAngle`, `startAngle`, `endAngle`, `strokeWidth` (default `3`), `strokeColor` (card background) | Shape |
95
+ | `withTooltip`, `tooltipDataSource` | The hovered `'segment'` with its share (default) or `'all'` slices. Off by default for Pie, on for Donut. Rendered into `document.body` outward from the center, so it neither covers the center label nor gets clipped by `overflow: hidden` cards |
96
+ | `withLegend`, `legendPosition` | Legend with hover highlight |
97
+ | `valueFormatter`, `pieProps`, `pieChartProps` | Formatting and recharts passthrough |
98
+ | `className`, `classNames` | Root class (backward-compatible) and per-part classes: `{ root, chart, legend }` |
99
+
100
+ ## RadialBarChart
101
+
102
+ ```tsx
103
+ <RadialBarChart
104
+ h={260}
105
+ dataKey="value"
106
+ withLabels
107
+ withLegend
108
+ data={[
109
+ { name: "18-24", value: 31.47, color: "blue-700" },
110
+ { name: "25-29", value: 26.69, color: "orange-600" },
111
+ ]}
112
+ />
113
+ ```
114
+
115
+ Props: `data`, `dataKey`, `h`, `w`, `barSize` (20), `withBackground` (true), `emptyBackgroundColor`, `startAngle` (90), `endAngle` (-270), `withLabels`, `withLegend`, `legendPosition`, `withTooltip` (true), `tooltipProps`, `valueFormatter`, `radialBarProps`, `radialBarChartProps`, `className`, `classNames` (`root`, `chart`, `legend`).
116
+
117
+ ## Heatmap
118
+
119
+ A contributions-style calendar (plain SVG, no recharts).
120
+
121
+ ```tsx
122
+ <Heatmap
123
+ data={{ "2025-02-14": 2, "2025-02-11": 3 }}
124
+ startDate="2025-01-01"
125
+ endDate="2025-03-31"
126
+ withMonthLabels
127
+ withWeekdayLabels
128
+ withLegend
129
+ withTooltip
130
+ getTooltipLabel={({ date, value }) => `${date}: ${value ?? 0}`}
131
+ />
132
+ ```
133
+
134
+ Every chart accepts `classNames={{ root, chart, legend }}` for its wrapper, plot area, and legend. The root is a card by default; use `classNames.root` to customize that card. `className` remains available for compatibility and is applied to the root.
135
+
136
+ | Prop | Description |
137
+ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
138
+ | `data` | `{ 'YYYY-MM-DD': number }` (UTC days) |
139
+ | `startDate`, `endDate` | Range (default: the year up to today) |
140
+ | `colors`, `domain` | Low → high colors (4 greens) and the `[min, max]` they span (from the data) |
141
+ | `firstDayOfWeek` | `0` Sunday … `6` Saturday (default `1`) |
142
+ | `rectSize`, `gap`, `rectRadius`, `fontSize` | Squares (10, 1, 2) and labels (12) |
143
+ | `withMonthLabels`, `monthLabels`, `monthLabelsPosition`, `monthsLabelsHeight` | Month row |
144
+ | `withWeekdayLabels`, `weekdayLabels`, `weekdaysLabelsWidth` | Weekday column (Sunday first; default shows Mon/Wed/Fri) |
145
+ | `splitMonths`, `withOutsideDates` | Gap between months; show the padding days of the first/last week |
146
+ | `withTooltip`, `getTooltipLabel`, `getRectProps` | Hover tooltip and per-square props |
147
+ | `withLegend`, `legendLabels` | `Less … More` scale |
148
+
149
+ ## Theming
150
+
151
+ Override any variable on `.wello-chart` (or a parent):
152
+
153
+ `--wello-chart-primary`, `--wello-chart-bg`, `--wello-chart-text-color`, `--wello-chart-bright-color`, `--wello-chart-dimmed-color`, `--wello-chart-grid-color`, `--wello-chart-cursor-fill`, `--wello-chart-tooltip-bg`, `--wello-chart-tooltip-fg`, `--wello-chart-heatmap-empty`, `--wello-chart-radial-bg`, `--wello-chart-label-line-color`, `--wello-chart-font`.
154
+
155
+ `ChartTooltip`, `ChartSliceTooltip`, `ChartLegend`, `getThemeColor`, `seriesColor`, `CHART_COLORS` and `DEFAULT_CHART_COLORS` are exported for custom tooltips and legends.