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

package/src/components/charts/RECHARTS_FEATURES.md

@@ -0,0 +1,458 @@
+# Recharts Native Features Usage
+
+This document details how our chart components leverage Recharts' built-in features for optimal performance and functionality.
+
+## Overview
+
+Our chart components are designed as **thin wrappers** around Recharts, utilizing its native capabilities wherever possible rather than implementing custom solutions. This approach ensures:
+
+- ✅ Better performance (native rendering)
+- ✅ Consistent behavior with Recharts ecosystem
+- ✅ Easier maintenance and updates
+- ✅ Access to full Recharts API when needed
+
+## Core Native Features
+
+### 1. Cell Component
+
+**What it is:** Recharts' built-in component for styling individual chart elements (bars, pie segments, etc.)
+
+**How we use it:**
+
+```tsx
+// In BarChart component
+<Bar dataKey="sales" fill="var(--color-sales)" radius={5}>
+  {data.map((entry, index) => (
+    <Cell 
+      key={`cell-${index}`} 
+      fill={customColor || defaultColor}
+    />
+  ))}
+</Bar>
+```
+
+**Benefits:**
+- Per-item customization without custom rendering
+- Conditional coloring based on data values
+- Native performance optimization
+
+**User-facing API:**
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["sales"]}
+  getBarColor={(entry, index, dataKey) => {
+    // Return custom color or undefined for default
+    return entry.sales > 200 ? "hsl(var(--destructive))" : undefined;
+  }}
+/>
+```
+
+### 2. Linear Gradients (SVG Defs)
+
+**What it is:** Recharts supports SVG `<defs>` for defining reusable graphics like gradients
+
+**How we use it:**
+
+```tsx
+// In BarChart component
+<defs>
+  {gradient && dataKeys.map((key) => (
+    <linearGradient
+      key={key}
+      id={`gradient-bar-${key}`}
+      x1={isVertical ? "1" : "0"}
+      y1={isVertical ? "0" : "0"}
+      x2={isVertical ? "0" : "0"}
+      y2={isVertical ? "0" : "1"}
+    >
+      <stop offset="0%" stopColor={`var(--color-${key})`} stopOpacity={1} />
+      <stop offset="100%" stopColor={`var(--color-${key})`} stopOpacity={0.1} />
+    </linearGradient>
+  ))}
+</defs>
+
+<Bar fill={gradient ? `url(#gradient-bar-${key})` : `var(--color-${key})`} />
+```
+
+**Benefits:**
+- Native SVG rendering
+- Automatic orientation handling
+- Hardware-accelerated graphics
+- Proper gradient direction per chart orientation
+
+**Gradient directions per chart type:**
+- **BarChart (vertical bars):** Top to bottom (`y1="0" y2="1"`)
+- **BarChart (horizontal bars):** Right to left (`x1="1" x2="0"`)
+- **AreaChart:** Top to bottom (`y1="0" y2="1"`)
+- **PieChart:** Radial from center (`radialGradient`)
+- **RadialBarChart:** Horizontal along bar (`x1="0" x2="1"`)
+
+### 3. Active Shape Props
+
+**What it is:** Recharts' built-in props for handling hover/active states
+
+**Available props:**
+- `activeShape` - Custom renderer for active element
+- `activeDot` - Active dot styling for line/area charts
+- `activeBar` - Active bar styling for bar charts
+
+**How we use it:**
+
+```tsx
+// In AreaChart component
+<Area
+  dataKey="revenue"
+  activeDot={
+    activeDot !== undefined 
+      ? activeDot 
+      : showDots ? { r: 4, strokeWidth: 2 } : undefined
+  }
+/>
+```
+
+**User-facing API:**
+
+```tsx
+<AreaChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["revenue"]}
+  showDots={true}
+  activeDot={{ r: 6, strokeWidth: 2, fill: "hsl(var(--primary))" }}
+/>
+```
+
+### 4. PolarGrid Component
+
+**What it is:** Recharts' component for rendering grids in polar coordinate systems
+
+**How we use it:**
+
+```tsx
+// In PieChart component
+<PolarGrid
+  gridType="circle"
+  radialLines={true}
+  polarAngles={Array.from(
+    { length: radialGridLines },
+    (_, i) => (360 / radialGridLines) * i
+  )}
+  stroke="hsl(var(--border))"
+  strokeOpacity={0.3}
+  strokeWidth={1}
+/>
+```
+
+**User-facing API:**
+
+```tsx
+<PieChart
+  data={data}
+  config={config}
+  nameKey="category"
+  dataKey="value"
+  showRadialGrid={true}
+  radialGridLines={12}
+/>
+```
+
+### 5. CartesianGrid Component
+
+**What it is:** Recharts' component for rendering grid lines in Cartesian charts
+
+**How we use it:**
+
+```tsx
+// In BarChart, AreaChart components
+<CartesianGrid
+  strokeDasharray="3 3"
+  horizontal={gridConfig.horizontal}
+  vertical={gridConfig.vertical}
+/>
+```
+
+**User-facing API:**
+
+```tsx
+// Boolean (both axes)
+<BarChart showGrid={true} />
+
+// Granular control
+<BarChart 
+  showGrid={{ 
+    horizontal: true, 
+    vertical: false 
+  }} 
+/>
+```
+
+### 6. Shape Prop (Custom Rendering)
+
+**What it is:** Recharts allows custom shape renderers for complete control
+
+**How we use it:**
+
+```tsx
+// In PieChart component for scaled radius
+const renderCustomShape = (props) => {
+  const { cx, cy, innerRadius, outerRadius, startAngle, endAngle, fill, value } = props;
+  
+  // Calculate scaled radius
+  let scaledOuterRadius = outerRadius;
+  if (scaledRadius && maxValue > 0) {
+    const percentage = Number(value) / maxValue;
+    scaledOuterRadius = outerRadius * (0.4 + percentage * 0.6);
+  }
+  
+  return (
+    <Sector
+      cx={cx}
+      cy={cy}
+      innerRadius={innerRadius}
+      outerRadius={scaledOuterRadius}
+      startAngle={startAngle}
+      endAngle={endAngle}
+      fill={fill}
+    />
+  );
+};
+
+<Pie shape={renderCustomShape} />
+```
+
+**User-facing API:**
+
+```tsx
+<PieChart
+  data={data}
+  config={config}
+  nameKey="category"
+  dataKey="value"
+  scaledRadius={true} // Segments scale based on value
+/>
+```
+
+## Implementation Patterns
+
+### Pattern 1: Conditional Rendering with Cell
+
+**Use case:** Color individual bars/segments based on data values
+
+```tsx
+{dataKeys.map((key) => (
+  <Bar key={key} dataKey={key} fill={defaultFill}>
+    {getBarColor && data.map((entry, index) => {
+      const customColor = getBarColor(entry, index, key);
+      return (
+        <Cell
+          key={`cell-${key}-${index}`}
+          fill={customColor || defaultFill}
+        />
+      );
+    })}
+  </Bar>
+))}
+```
+
+### Pattern 2: Dynamic Gradient Definitions
+
+**Use case:** Create gradients that adapt to chart configuration
+
+```tsx
+<defs>
+  {gradient && dataKeys.map((key) => (
+    <linearGradient
+      key={key}
+      id={`gradient-${chartType}-${key}`}
+      x1={orientation === "horizontal" ? "1" : "0"}
+      y1={orientation === "horizontal" ? "0" : "0"}
+      x2={orientation === "horizontal" ? "0" : "0"}
+      y2={orientation === "horizontal" ? "0" : "1"}
+    >
+      <stop offset="0%" stopColor={`var(--color-${key})`} stopOpacity={1} />
+      <stop offset="100%" stopColor={`var(--color-${key})`} stopOpacity={0.1} />
+    </linearGradient>
+  ))}
+</defs>
+```
+
+### Pattern 3: Responsive Container
+
+**Use case:** Charts that adapt to parent container size
+
+```tsx
+// We use ChartContainer which wraps ResponsiveContainer
+<ChartContainer config={config} className={grow ? "h-full w-full" : aspectRatio}>
+  <RechartsBarChart data={data}>
+    {/* chart elements */}
+  </RechartsBarChart>
+</ChartContainer>
+```
+
+## Why Native Features Matter
+
+### Performance
+
+Native Recharts features are optimized for:
+- Efficient SVG rendering
+- Minimal re-renders
+- Hardware acceleration where possible
+- React reconciliation optimization
+
+### Maintainability
+
+Using native features means:
+- Fewer custom implementations to maintain
+- Easier to update when Recharts updates
+- Better TypeScript support
+- Consistent with Recharts documentation
+
+### Extensibility
+
+Users can:
+- Pass additional Recharts props through
+- Extend components without rewriting
+- Use Recharts plugins and extensions
+- Access full Recharts ecosystem
+
+## Examples
+
+### Example 1: Traffic Light Colors
+
+```tsx
+const data = [
+  { status: "Critical", count: 12 },
+  { status: "Warning", count: 45 },
+  { status: "Good", count: 89 },
+];
+
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="status"
+  dataKeys={["count"]}
+  getBarColor={(entry) => {
+    switch (entry.status) {
+      case "Critical": return "hsl(0 84% 60%)";      // Red
+      case "Warning": return "hsl(48 96% 53%)";      // Yellow
+      case "Good": return "hsl(142 76% 36%)";        // Green
+      default: return undefined;
+    }
+  }}
+/>
+```
+
+### Example 2: Threshold-Based Coloring
+
+```tsx
+const data = [
+  { month: "Jan", revenue: 1200, target: 1000 },
+  { month: "Feb", revenue: 800, target: 1000 },
+  { month: "Mar", revenue: 1500, target: 1000 },
+];
+
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["revenue"]}
+  getBarColor={(entry) => {
+    const percentage = (entry.revenue / entry.target) * 100;
+    if (percentage >= 100) return "hsl(142 76% 36%)";    // Green: Met target
+    if (percentage >= 80) return "hsl(48 96% 53%)";      // Yellow: Close
+    return "hsl(0 84% 60%)";                              // Red: Below target
+  }}
+/>
+```
+
+### Example 3: Gradient with Conditional Override
+
+```tsx
+<BarChart
+  data={data}
+  config={config}
+  categoryKey="month"
+  dataKeys={["sales"]}
+  gradient={true}
+  getBarColor={(entry) => {
+    // Highlight special cases with solid color, let others use gradient
+    if (entry.month === "Dec") {
+      return "hsl(var(--primary))"; // Solid color for December
+    }
+    return undefined; // Use gradient for others
+  }}
+/>
+```
+
+### Example 4: Interactive Area Chart
+
+```tsx
+<AreaChart
+  data={data}
+  config={config}
+  categoryKey="date"
+  dataKeys={["value"]}
+  gradient={true}
+  showDots={true}
+  activeDot={{
+    r: 6,
+    strokeWidth: 2,
+    fill: "hsl(var(--primary))",
+    stroke: "hsl(var(--background))",
+  }}
+  curveType="monotone"
+/>
+```
+
+## Best Practices
+
+### ✅ Do
+
+- Use `Cell` component for per-item customization
+- Leverage native gradient support via `<defs>`
+- Use Recharts' active state props for hover effects
+- Keep gradient IDs unique per chart instance
+- Return `undefined` from color functions to use defaults
+
+### ❌ Don't
+
+- Implement custom rendering when native features suffice
+- Hardcode gradient definitions outside `<defs>`
+- Override all Recharts styles (let native theming work)
+- Ignore orientation when defining gradients
+- Create duplicate gradient definitions
+
+## Future Enhancements
+
+Potential native features to explore:
+
+1. **Brush component** - For data zooming/panning
+2. **ReferenceLines** - For threshold indicators
+3. **ReferenceDots** - For specific data point highlighting
+4. **Customized Label** - For advanced label positioning
+5. **Legend customization** - Using native Legend props
+6. **Animation props** - Recharts' native animation system
+
+## Resources
+
+- [Recharts Documentation](https://recharts.org/)
+- [Recharts API Reference](https://recharts.org/en-US/api)
+- [Recharts GitHub](https://github.com/recharts/recharts)
+- [SVG Gradients MDN](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient)
+
+## Summary
+
+Our chart components are **Recharts-first** implementations that:
+
+1. **Expose native Recharts features** through clean, typed APIs
+2. **Enhance with convenience props** while maintaining Recharts compatibility
+3. **Use Cell, gradients, and native props** for styling and interactivity
+4. **Avoid custom rendering** unless absolutely necessary
+5. **Stay compatible** with Recharts ecosystem and updates
+
+This approach gives users the full power of Recharts while providing sensible defaults and TypeScript safety.

package/src/components/charts/area-chart.tsx

@@ -0,0 +1,248 @@
+"use client";
+
+import { Area, AreaChart as RechartsAreaChart, CartesianGrid, XAxis, YAxis, Dot } from "recharts";
+import {
+  ChartConfig,
+  ChartContainer,
+  ChartLegend,
+  ChartLegendContent,
+  ChartTooltip,
+  ChartTooltipContent,
+} from "../ui/chart";
+import { cn } from "@/lib/utils";
+
+export interface AreaChartData {
+  [key: string]: string | number;
+}
+
+export interface AreaChartProps {
+  /**
+   * Array of data objects to be displayed in the chart
+   */
+  data: AreaChartData[];
+  /**
+   * Configuration for chart styling and labels
+   */
+  config: ChartConfig;
+  /**
+   * Key from data objects to use for X-axis categories
+   */
+  categoryKey: string;
+  /**
+   * Array of keys from data objects to display as areas
+   */
+  dataKeys: string[];
+  /**
+   * Show grid lines. Can be boolean for both axes or object for granular control
+   * @default true
+   */
+  showGrid?: boolean | { horizontal?: boolean; vertical?: boolean };
+  /**
+   * Show legend
+   * @default false
+   */
+  showLegend?: boolean;
+  /**
+   * Show tooltip on hover
+   * @default true
+   */
+  showTooltip?: boolean;
+  /**
+   * Stack areas on top of each other
+   * @default false
+   */
+  stacked?: boolean;
+  /**
+   * Area curve type
+   * @default "monotone"
+   */
+  curveType?:
+    | "basis"
+    | "basisClosed"
+    | "basisOpen"
+    | "linear"
+    | "linearClosed"
+    | "natural"
+    | "monotoneX"
+    | "monotoneY"
+    | "monotone"
+    | "step"
+    | "stepBefore"
+    | "stepAfter";
+  /**
+   * Fill opacity for areas
+   * @default 0.6
+   */
+  fillOpacity?: number;
+  /**
+   * Stroke width for area lines
+   * @default 2
+   */
+  strokeWidth?: number;
+  /**
+   * Enable gradient fill for areas (uses Recharts native gradient support)
+   * @default true
+   */
+  gradient?: boolean;
+  /**
+   * Active dot props for highlighting data points on hover
+   * @default undefined
+   */
+  activeDot?: boolean | object;
+  /**
+   * Custom className for the container
+   */
+  className?: string;
+  /**
+   * Chart height aspect ratio
+   * @default "aspect-video"
+   */
+  aspectRatio?: string;
+  /**
+   * Make chart grow to fill parent container (ignores aspectRatio if true)
+   * @default false
+   */
+  grow?: boolean;
+  /**
+   * Show dots on data points
+   * @default false
+   */
+  showDots?: boolean;
+  /**
+   * Custom formatter function for Y-axis tick labels
+   * @example (value) => `$${value.toLocaleString()}`
+   * @example (value) => formatCompactNumber(value)
+   */
+  yAxisFormatter?: (value: number) => string;
+  /**
+   * Custom formatter function for X-axis tick labels
+   * @example (value) => new Date(value).toLocaleDateString()
+   * @example (value) => formatCompactNumber(value)
+   */
+  xAxisFormatter?: (value: any) => string;
+  /**
+   * Custom formatter function for tooltip values
+   * @example (value, name, item, index, payload) => `$${value.toLocaleString()}`
+   */
+  tooltipFormatter?: (
+    value: any,
+    name: any,
+    item: any,
+    index: number,
+    payload: any
+  ) => React.ReactNode;
+}
+
+export function AreaChart({
+  data,
+  config,
+  categoryKey,
+  dataKeys,
+  showGrid = true,
+  showLegend = false,
+  showTooltip = true,
+  stacked = false,
+  curveType = "monotone",
+  fillOpacity = 0.6,
+  strokeWidth = 2,
+  gradient = true,
+  className,
+  aspectRatio = "aspect-video",
+  showDots = false,
+  grow = false,
+  activeDot,
+  yAxisFormatter,
+  xAxisFormatter,
+  tooltipFormatter,
+}: AreaChartProps) {
+  const stackId = stacked ? "stack" : undefined;
+
+  // Parse grid configuration
+  const gridConfig =
+    typeof showGrid === "boolean"
+      ? { horizontal: showGrid, vertical: showGrid }
+      : { horizontal: showGrid?.horizontal ?? false, vertical: showGrid?.vertical ?? false };
+
+  return (
+    <ChartContainer config={config} className={cn(grow ? "h-full w-full" : aspectRatio, className)}>
+      <RechartsAreaChart
+        accessibilityLayer
+        data={data}
+        margin={{
+          top: 10,
+          right: 10,
+          bottom: 10,
+          left: 10,
+        }}
+      >
+        {(gridConfig.horizontal || gridConfig.vertical) && (
+          <CartesianGrid
+            strokeDasharray="3 3"
+            horizontal={gridConfig.horizontal}
+            vertical={gridConfig.vertical}
+          />
+        )}
+
+        <XAxis
+          dataKey={categoryKey}
+          tickLine={false}
+          tickMargin={10}
+          axisLine={false}
+          tickFormatter={(value) => {
+            if (xAxisFormatter) {
+              return xAxisFormatter(value);
+            }
+            return config[value as keyof typeof config]?.label?.toString() || value;
+          }}
+        />
+        <YAxis
+          tickLine={false}
+          axisLine={false}
+          tickFormatter={(value) => (yAxisFormatter ? yAxisFormatter(value) : value)}
+          width={yAxisFormatter ? 50 : undefined}
+        />
+
+        {showTooltip && (
+          <ChartTooltip
+            cursor={false}
+            content={
+              <ChartTooltipContent
+                indicator={stacked ? "line" : "dot"}
+                formatter={tooltipFormatter}
+              />
+            }
+          />
+        )}
+
+        {showLegend && <ChartLegend content={<ChartLegendContent />} />}
+
+        <defs>
+          {gradient &&
+            dataKeys.map((key) => (
+              <linearGradient key={key} id={`gradient-area-${key}`} x1="0" y1="0" x2="0" y2="1">
+                <stop offset="0%" stopColor={`var(--color-${key})`} stopOpacity={0.6} />
+                <stop offset="100%" stopColor={`var(--color-${key})`} stopOpacity={0.05} />
+              </linearGradient>
+            ))}
+        </defs>
+
+        {dataKeys.map((key) => (
+          <Area
+            key={key}
+            dataKey={key}
+            type={curveType}
+            fill={gradient ? `url(#gradient-area-${key})` : `var(--color-${key})`}
+            stroke={`var(--color-${key})`}
+            fillOpacity={gradient ? 1 : fillOpacity}
+            strokeWidth={strokeWidth}
+            stackId={stackId}
+            dot={showDots}
+            activeDot={
+              activeDot !== undefined ? activeDot : showDots ? { r: 4, strokeWidth: 2 } : undefined
+            }
+          />
+        ))}
+      </RechartsAreaChart>
+    </ChartContainer>
+  );
+}