@turtleclub/ui 0.7.0-beta.3 → 0.7.0-beta.30

package/src/components/charts/README.md

@@ -0,0 +1,658 @@
+# Chart Components
+
+Standardized, reusable chart components built with [Recharts](https://recharts.org/) and fully typed with TypeScript. These components provide a consistent interface for creating beautiful, interactive charts with minimal configuration.
+
+**Note:** These components leverage Recharts' native features and props wherever possible, including:
+
+- Native `Cell` component for per-item styling and conditional coloring
+- Built-in gradient support via `<defs>` and `linearGradient`
+- Native `activeShape`, `activeDot`, and `activeBar` props for hover states
+- Recharts' responsive container system
+- Native accessibility features
+
+## Features
+
+- 🎨 **Consistent Styling** - Uses your theme's CSS variables for colors
+- 📊 **Multiple Chart Types** - Bar, Area, Pie, and Radial charts
+- 🔧 **Fully Typed** - Complete TypeScript support with clear interfaces
+- 🎯 **Easy to Use** - Simple, declarative API
+- 📱 **Responsive** - Automatically adapts to container size
+- ♿ **Accessible** - Built with accessibility in mind
+- 🎨 **Customizable** - Extensive props for customization
+- ⚡ **Native Recharts Features** - Leverages Recharts' built-in capabilities for optimal performance
+
+## Available Charts
+
+- **BarChart** - Horizontal and vertical bar charts, single or multi-series, stacked
+- **AreaChart** - Smooth area charts with multiple curve types, stacked support
+- **PieChart** - Pie and donut charts with labels and legends
+- **RadialBarChart** - Circular progress indicators
+- **RadarChart** - Multi-dimensional data visualization
+
+## Installation
+
+These components are part of the `@turtleclub/ui` package and depend on `recharts`:
+
+```bash
+npm install recharts
+```
+
+## Basic Usage
+
+### Bar Chart
+
+```tsx
+import { BarChart } from "@turtleclub/ui";
+import type { ChartConfig } from "@turtleclub/ui";
+
+const data = [
+  { month: "Jan", sales: 186 },
+  { month: "Feb", sales: 305 },
+  { month: "Mar", sales: 237 },
+];
+
+const config = {
+  sales: {
+    label: "Sales",
+    color: "var(--chart-1)",
+  },
+} satisfies ChartConfig;
+
+function MyChart() {
+  return <BarChart data={data} config={config} categoryKey="month" dataKeys={["sales"]} />;
+}
+```
+
+### Area Chart
+
+```tsx
+import { AreaChart } from "@turtleclub/ui";
+
+const data = [
+  { month: "Jan", revenue: 2400, expenses: 1800 },
+  { month: "Feb", revenue: 1398, expenses: 1200 },
+  { month: "Mar", revenue: 9800, expenses: 2200 },
+];
+
+const config = {
+  revenue: {
+    label: "Revenue",
+    color: "var(--chart-1)",
+  },
+  expenses: {
+    label: "Expenses",
+    color: "var(--chart-2)",
+  },
+} satisfies ChartConfig;
+
+function MyChart() {
+  return (
+    <AreaChart
+      data={data}
+      config={config}
+      categoryKey="month"
+      dataKeys={["revenue", "expenses"]}
+      showLegend={true}
+    />
+  );
+}
+```
+
+### Pie Chart
+
+```tsx
+import { PieChart } from "@turtleclub/ui";
+
+const data = [
+  { category: "electronics", value: 35 },
+  { category: "clothing", value: 25 },
+  { category: "food", value: 20 },
+];
+
+const config = {
+  electronics: { label: "Electronics", color: "var(--chart-1)" },
+  clothing: { label: "Clothing", color: "var(--chart-2)" },
+  food: { label: "Food", color: "var(--chart-3)" },
+} satisfies ChartConfig;
+
+function MyChart() {
+  return (
+    <PieChart data={data} config={config} nameKey="category" dataKey="value" showLegend={true} />
+  );
+}
+```
+
+### Radial Charts
+
+```tsx
+import { RadialBarChart, RadarChart } from "@turtleclub/ui";
+
+// Radial Bar Chart (Full Circle)
+const radialData = [
+  { metric: "performance", value: 85, fill: "var(--color-performance)" },
+  { metric: "quality", value: 92, fill: "var(--color-quality)" },
+];
+
+const radialConfig = {
+  performance: { label: "Performance", color: "var(--chart-1)" },
+  quality: { label: "Quality", color: "var(--chart-2)" },
+} satisfies ChartConfig;
+
+function MyRadialChart() {
+  return (
+    <RadialBarChart data={radialData} config={radialConfig} nameKey="metric" dataKey="value" />
+  );
+}
+
+// Semi-Circle Radial Chart (Half Circle) - Multiple Values
+const semiCircleData = [
+  { metric: "design", value: 88, fill: "var(--color-design)" },
+  { metric: "development", value: 72, fill: "var(--color-development)" },
+  { metric: "testing", value: 65, fill: "var(--color-testing)" },
+  { metric: "deployment", value: 45, fill: "var(--color-deployment)" },
+];
+
+const semiCircleConfig = {
+  design: { label: "Design", color: "var(--chart-1)" },
+  development: { label: "Development", color: "var(--chart-2)" },
+  testing: { label: "Testing", color: "var(--chart-3)" },
+  deployment: { label: "Deployment", color: "var(--chart-4)" },
+} satisfies ChartConfig;
+
+function MySemiCircleChart() {
+  return (
+    <RadialBarChart
+      data={semiCircleData}
+      config={semiCircleConfig}
+      nameKey="metric"
+      dataKey="value"
+      startAngle={180}
+      endAngle={0}
+      innerRadius={60}
+      outerRadius={80}
+    />
+  );
+}
+
+// Radar Chart
+const radarData = [
+  { skill: "coding", current: 85, target: 90 },
+  { skill: "design", current: 70, target: 85 },
+];
+
+const radarConfig = {
+  current: { label: "Current", color: "var(--chart-1)" },
+  target: { label: "Target", color: "var(--chart-2)" },
+} satisfies ChartConfig;
+
+function MyRadarChart() {
+  return (
+    <RadarChart
+      data={radarData}
+      config={radarConfig}
+      categoryKey="skill"
+      dataKeys={["current", "target"]}
+    />
+  );
+}
+```
+
+## ChartConfig
+
+All charts require a `config` object that defines the styling and labels for your data. The config uses CSS variables from your theme:
+
+```tsx
+const config = {
+  // For data series
+  sales: {
+    label: "Sales",
+    color: "var(--chart-1)", // Use theme colors
+  },
+  // For categories (optional label override)
+  january: {
+    label: "Jan",
+  },
+} satisfies ChartConfig;
+```
+
+### Theme Colors
+
+Use these CSS variables in your config:
+
+- `var(--chart-1)` - Primary chart color
+- `var(--chart-2)` - Secondary chart color
+- `var(--chart-3)` - Tertiary chart color
+- `var(--chart-4)` - Quaternary chart color
+- `var(--chart-5)` - Quinary chart color
+
+## Recharts Native Features
+
+These components are designed to leverage Recharts' native features for optimal performance and flexibility:
+
+### Cell Component (Used in BarChart, PieChart, RadialBarChart)
+
+The `Cell` component allows per-item customization of chart elements. Our components use this for:
+
+- Conditional coloring based on data values
+- Per-segment styling in pie charts
+- Individual bar coloring in bar charts
+
+Example with conditional coloring:
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["sales"]}
+  getBarColor={(entry, index, dataKey) => {
+    // Color bars differently based on value
+    return entry.sales > 200 ? "hsl(var(--destructive))" : undefined;
+  }}
+/>
+```
+
+### Native Gradient Support
+
+All charts use Recharts' native `<defs>` and `linearGradient` for gradient fills:
+
+- **BarChart**: Gradients adapt to chart orientation (vertical/horizontal)
+- **AreaChart**: Top-to-bottom gradients for filled areas
+- **PieChart**: Radial gradients from center outward
+- **RadialBarChart**: Radial gradients for circular progress
+
+### Active States
+
+Recharts provides built-in hover/active states:
+
+- `activeShape` prop for custom active rendering
+- `activeDot` prop for highlighting data points
+- `activeBar` prop for bar hover effects
+
+Example:
+
+```tsx
+<AreaChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["revenue"]}
+  showDots={true}
+  activeDot={{ r: 6, strokeWidth: 2 }}
+/>
+```
+
+### PolarGrid for Radial Lines
+
+The `PolarGrid` component provides native support for radial guidelines:
+
+```tsx
+<PieChart
+  data={data}
+  config={config}
+  nameKey="category"
+  dataKey="value"
+  showRadialGrid={true}
+  radialGridLines={12}
+/>
+```
+
+## API Reference
+
+### BarChart Props
+
+| Prop          | Type                         | Default          | Description                                               |
+| ------------- | ---------------------------- | ---------------- | --------------------------------------------------------- |
+| `data`        | `BarChartData[]`             | Required         | Array of data objects                                     |
+| `config`      | `ChartConfig`                | Required         | Chart configuration                                       |
+| `categoryKey` | `string`                     | Required         | Key for X-axis categories                                 |
+| `dataKeys`    | `string[]`                   | Required         | Array of keys for bars                                    |
+| `layout`      | `"horizontal" \| "vertical"` | `"horizontal"`   | Chart orientation                                         |
+| `showGrid`    | `boolean`                    | `true`           | Show grid lines                                           |
+| `showLegend`  | `boolean`                    | `false`          | Show legend                                               |
+| `showTooltip` | `boolean`                    | `true`           | Show tooltip                                              |
+| `stacked`     | `boolean`                    | `false`          | Stack bars                                                |
+| `barRadius`   | `number`                     | `5`              | Border radius for bars                                    |
+| `gradient`    | `boolean`                    | `false`          | Enable gradient fill (uses Recharts native gradients)     |
+| `getBarColor` | `function`                   | `undefined`      | Function to conditionally color bars based on data values |
+| `className`   | `string`                     | `undefined`      | Custom className                                          |
+| `aspectRatio` | `string`                     | `"aspect-video"` | Aspect ratio class                                        |
+| `grow`        | `boolean`                    | `false`          | Fill parent container                                     |
+
+### AreaChart Props
+
+| Prop          | Type                | Default          | Description                                           |
+| ------------- | ------------------- | ---------------- | ----------------------------------------------------- |
+| `data`        | `AreaChartData[]`   | Required         | Array of data objects                                 |
+| `config`      | `ChartConfig`       | Required         | Chart configuration                                   |
+| `categoryKey` | `string`            | Required         | Key for X-axis categories                             |
+| `dataKeys`    | `string[]`          | Required         | Array of keys for areas                               |
+| `showGrid`    | `boolean`           | `true`           | Show grid lines                                       |
+| `showLegend`  | `boolean`           | `false`          | Show legend                                           |
+| `showTooltip` | `boolean`           | `true`           | Show tooltip                                          |
+| `stacked`     | `boolean`           | `false`          | Stack areas                                           |
+| `gradient`    | `boolean`           | `true`           | Enable gradient fill (uses Recharts native gradients) |
+| `activeDot`   | `boolean \| object` | `undefined`      | Active dot props for hover states (Recharts native)   |
+| `showDots`    | `boolean`           | `false`          | Show dots on data points                              |
+| `grow`        | `boolean`           | `false`          | Fill parent container                                 |
+| `curveType`   | `string`            | `"monotone"`     | Curve interpolation type                              |
+| `fillOpacity` | `number`            | `0.2`            | Fill opacity                                          |
+| `strokeWidth` | `number`            | `2`              | Line stroke width                                     |
+| `showDots`    | `boolean`           | `false`          | Show data point dots                                  |
+| `className`   | `string`            | `undefined`      | Custom className                                      |
+| `aspectRatio` | `string`            | `"aspect-video"` | Aspect ratio class                                    |
+
+### PieChart Props
+
+| Prop             | Type             | Default           | Description                        |
+| ---------------- | ---------------- | ----------------- | ---------------------------------- |
+| `data`           | `PieChartData[]` | Required          | Array of data objects              |
+| `config`         | `ChartConfig`    | Required          | Chart configuration                |
+| `nameKey`        | `string`         | Required          | Key for segment names              |
+| `dataKey`        | `string`         | Required          | Key for segment values             |
+| `showLegend`     | `boolean`        | `true`            | Show legend                        |
+| `showTooltip`    | `boolean`        | `true`            | Show tooltip                       |
+| `showLabels`     | `boolean`        | `false`           | Show segment labels                |
+| `innerRadius`    | `number`         | `0`               | Inner radius (0 = pie, >0 = donut) |
+| `outerRadius`    | `number`         | `80`              | Outer radius                       |
+| `paddingAngle`   | `number`         | `0`               | Padding between segments           |
+| `labelFormatter` | `function`       | `undefined`       | Custom label formatter             |
+| `className`      | `string`         | `undefined`       | Custom className                   |
+| `aspectRatio`    | `string`         | `"aspect-square"` | Aspect ratio class                 |
+
+### RadialBarChart Props
+
+| Prop           | Type                | Default           | Description            |
+| -------------- | ------------------- | ----------------- | ---------------------- |
+| `data`         | `RadialChartData[]` | Required          | Array of data objects  |
+| `config`       | `ChartConfig`       | Required          | Chart configuration    |
+| `nameKey`      | `string`            | Required          | Key for segment names  |
+| `dataKey`      | `string`            | Required          | Key for values         |
+| `showLegend`   | `boolean`           | `false`           | Show legend            |
+| `showTooltip`  | `boolean`           | `true`            | Show tooltip           |
+| `innerRadius`  | `number`            | `30`              | Inner radius           |
+| `outerRadius`  | `number`            | `100`             | Outer radius           |
+| `startAngle`   | `number`            | `90`              | Start angle in degrees |
+| `endAngle`     | `number`            | `-270`            | End angle in degrees   |
+| `showLabels`   | `boolean`           | `false`           | Show labels on bars    |
+| `cornerRadius` | `number`            | `10`              | Corner radius for bars |
+| `className`    | `string`            | `undefined`       | Custom className       |
+| `aspectRatio`  | `string`            | `"aspect-square"` | Aspect ratio class     |
+
+### RadarChart Props
+
+| Prop          | Type                | Default           | Description                   |
+| ------------- | ------------------- | ----------------- | ----------------------------- |
+| `data`        | `RadialChartData[]` | Required          | Array of data objects         |
+| `config`      | `ChartConfig`       | Required          | Chart configuration           |
+| `categoryKey` | `string`            | Required          | Key for categories            |
+| `dataKeys`    | `string[]`          | Required          | Array of keys for radar areas |
+| `showLegend`  | `boolean`           | `false`           | Show legend                   |
+| `showTooltip` | `boolean`           | `true`            | Show tooltip                  |
+| `showDots`    | `boolean`           | `true`            | Show data point dots          |
+| `fillOpacity` | `number`            | `0.6`             | Fill opacity                  |
+| `strokeWidth` | `number`            | `2`               | Line stroke width             |
+| `className`   | `string`            | `undefined`       | Custom className              |
+| `aspectRatio` | `string`            | `"aspect-square"` | Aspect ratio class            |
+
+## Advanced Usage
+
+### Wrapping in Cards
+
+For better presentation, wrap charts in Card components:
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@turtleclub/ui";
+import { BarChart } from "@turtleclub/ui";
+
+function MyChart() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Monthly Sales</CardTitle>
+        <CardDescription>Sales data for Q1 2024</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <BarChart data={data} config={config} categoryKey="month" dataKeys={["sales"]} />
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### Multi-Series Charts
+
+Display multiple data series by passing multiple keys:
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["desktop", "mobile", "tablet"]}
+  showLegend={true}
+/>
+```
+
+### Stacked Charts
+
+Stack data series on top of each other:
+
+```tsx
+<AreaChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["revenue", "expenses"]}
+  stacked={true}
+  showLegend={true}
+/>
+```
+
+### Conditional Bar Coloring
+
+Use the `getBarColor` prop to conditionally color bars based on their values. This leverages Recharts' native `Cell` component:
+
+```tsx
+const data = [
+  { month: "Jan", sales: 186, target: 200 },
+  { month: "Feb", sales: 305, target: 200 },
+  { month: "Mar", sales: 150, target: 200 },
+];
+
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["sales"]}
+  getBarColor={(entry, index, dataKey) => {
+    // Color bars red if below target, green if above
+    if (entry.sales < entry.target) {
+      return "hsl(var(--destructive))";
+    } else if (entry.sales > entry.target) {
+      return "hsl(var(--success))";
+    }
+    // Return undefined to use default color
+    return undefined;
+  }}
+/>;
+```
+
+**Multiple data keys with conditional coloring:**
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["desktop", "mobile"]}
+  getBarColor={(entry, index, dataKey) => {
+    // Different logic per data key
+    if (dataKey === "desktop" && entry.desktop > 500) {
+      return "hsl(142 76% 36%)"; // Green for high desktop sales
+    }
+    if (dataKey === "mobile" && entry.mobile < 100) {
+      return "hsl(346 87% 43%)"; // Red for low mobile sales
+    }
+    return undefined; // Use default from config
+  }}
+/>
+```
+
+**Gradient with conditional transparency:**
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["revenue"]}
+  gradient={true}
+  getBarColor={(entry, index, dataKey) => {
+    // Show low values with reduced opacity
+    if (entry.revenue < 1000) {
+      return "rgba(var(--chart-1-rgb), 0.3)";
+    }
+    return undefined; // Use gradient for normal values
+  }}
+/>
+```
+
+### Custom Aspect Ratios
+
+Change the chart dimensions:
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["sales"]}
+  aspectRatio="aspect-square"
+/>
+```
+
+Available options: `aspect-square`, `aspect-video`, `aspect-[4/3]`, or any custom Tailwind aspect ratio class.
+
+### Donut Charts
+
+Create donut charts by setting the inner radius:
+
+```tsx
+<PieChart
+  data={data}
+  config={config}
+  nameKey="category"
+  dataKey="value"
+  innerRadius={60}
+  showLegend={true}
+/>
+```
+
+### Semi-Circle Radial Charts
+
+Create half-circle gauges with multiple progress indicators using `startAngle` and `endAngle`:
+
+```tsx
+// Semi-circle (180° arc) with multiple metrics
+const data = [
+  { metric: "design", value: 88, fill: "var(--color-design)" },
+  { metric: "development", value: 72, fill: "var(--color-development)" },
+  { metric: "testing", value: 65, fill: "var(--color-testing)" },
+  { metric: "deployment", value: 45, fill: "var(--color-deployment)" },
+];
+
+const config = {
+  design: { label: "Design", color: "var(--chart-1)" },
+  development: { label: "Development", color: "var(--chart-2)" },
+  testing: { label: "Testing", color: "var(--chart-3)" },
+  deployment: { label: "Deployment", color: "var(--chart-4)" },
+} satisfies ChartConfig;
+
+<RadialBarChart
+  data={data}
+  config={config}
+  nameKey="metric"
+  dataKey="value"
+  startAngle={180}
+  endAngle={0}
+  innerRadius={60}
+  outerRadius={80}
+  showLegend={true}
+/>
+
+// Three-quarter circle (270° arc)
+<RadialBarChart
+  data={data}
+  config={config}
+  nameKey="metric"
+  dataKey="value"
+  startAngle={135}
+  endAngle={-135}
+/>
+
+// Quarter circle (90° arc)
+<RadialBarChart
+  data={data}
+  config={config}
+  nameKey="metric"
+  dataKey="value"
+  startAngle={180}
+  endAngle={90}
+/>
+```
+
+## Examples
+
+See the showcase app at `/components/charts` for comprehensive examples of all chart types with various configurations.
+
+## Best Practices
+
+1. **Use semantic color variables** - Use `--chart-1` through `--chart-5` for consistency
+2. **Provide clear labels** - Always configure meaningful labels in your ChartConfig
+3. **Keep data clean** - Ensure data keys match your config keys
+4. **Consider accessibility** - Use legends and tooltips for better understanding
+5. **Responsive design** - Charts automatically resize, but consider mobile layout
+6. **Performance** - For large datasets (>100 points), consider data aggregation
+
+## TypeScript Support
+
+All components are fully typed. Import types as needed:
+
+```tsx
+import type { BarChartData, BarChartProps, ChartConfig } from "@turtleclub/ui";
+```
+
+## Troubleshooting
+
+### Colors not showing
+
+Ensure your theme has the chart color variables defined:
+
+```css
+:root {
+  --chart-1: var(--color-brand-green); /* Primary chart color */
+  --chart-2: var(--color-info); /* Secondary chart color */
+  --chart-3: var(--color-warning); /* Tertiary chart color */
+  --chart-4: var(--color-error); /* Quaternary chart color */
+  --chart-5: var(--color-success); /* Quinary chart color */
+}
+```
+
+### Data not appearing
+
+Check that:
+
+- `dataKeys` match keys in your data objects
+- `categoryKey` matches a key in your data objects
+- Data is properly formatted as an array of objects
+
+### TypeScript errors
+
+Make sure to use `satisfies ChartConfig` on your config objects:
+
+```tsx
+const config = {
+  sales: { label: "Sales", color: "hsl(var(--chart-1))" },
+} satisfies ChartConfig;
+```