feat(pygal): implement area-basic

Add basic area chart implementation for pygal library.

- Create spec file: specs/area-basic.md
- Create implementation: plots/pygal/line/area-basic/default.py
- Uses pygal.Line with fill=True for area chart effect
- Includes sample data and test script

Author: github-actions[bot]

plots/pygal/line/area-basic/default.py

@@ -0,0 +1,147 @@
+"""
+area-basic: Basic Area Chart
+Implementation for: pygal
+Variant: default
+Python: 3.10+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import pandas as pd
+import pygal
+from pygal.style import Style
+
+
+if TYPE_CHECKING:
+    from pygal import Line
+
+
+def create_plot(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    title: Optional[str] = None,
+    xlabel: Optional[str] = None,
+    ylabel: Optional[str] = None,
+    fill_alpha: float = 0.5,
+    color: Optional[str] = None,
+    show_line: bool = True,
+    width: int = 1600,
+    height: int = 900,
+    **kwargs,
+) -> "Line":
+    """
+    Create a basic area chart showing a filled area under a line using pygal.
+
+    An area chart displays a single data series as a filled region beneath
+    a line, ideal for showing trends while emphasizing magnitude.
+
+    Args:
+        data: Input DataFrame with required columns
+        x: Column name for x-axis values (categories/labels)
+        y: Column name for y-axis numeric values
+        title: Chart title (optional)
+        xlabel: Custom x-axis label (optional, defaults to column name)
+        ylabel: Custom y-axis label (optional, defaults to column name)
+        fill_alpha: Transparency of the filled area (default: 0.5)
+        color: Color for the line and fill (optional)
+        show_line: Whether to show the line on top of fill (default: True)
+        width: Figure width in pixels (default: 1600)
+        height: Figure height in pixels (default: 900)
+        **kwargs: Additional parameters for pygal configuration
+
+    Returns:
+        pygal Line chart object configured as an area chart
+
+    Raises:
+        ValueError: If data is empty
+        KeyError: If required columns not found
+
+    Example:
+        >>> data = pd.DataFrame({
+        ...     'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+        ...     'Sales': [100, 150, 130, 180, 200]
+        ... })
+        >>> chart = create_plot(data, x='Month', y='Sales')
+    """
+    # Input validation
+    if data.empty:
+        raise ValueError("Data cannot be empty")
+
+    # Check required columns
+    for col in [x, y]:
+        if col not in data.columns:
+            available = ", ".join(data.columns)
+            raise KeyError(f"Column '{col}' not found. Available columns: {available}")
+
+    # Define colors - use provided color or default
+    primary_color = color or "#3498db"
+
+    # Create custom style with appropriate opacity for fill
+    custom_style = Style(
+        background="white",
+        plot_background="white",
+        foreground="#333",
+        foreground_strong="#333",
+        foreground_subtle="#555",
+        opacity=fill_alpha,
+        opacity_hover=min(fill_alpha + 0.2, 1.0),
+        colors=(primary_color,),
+        font_family="Arial, sans-serif",
+        major_guide_stroke_dasharray="3,3",
+        guide_stroke_dasharray="1,1",
+    )
+
+    # Create line chart with fill enabled (makes it an area chart)
+    chart = pygal.Line(
+        title=title or "Area Chart",
+        x_title=xlabel or x,
+        y_title=ylabel or y,
+        width=width,
+        height=height,
+        fill=True,  # This enables the area fill
+        show_legend=True,
+        style=custom_style,
+        show_x_guides=True,
+        show_y_guides=True,
+        dots_size=3 if show_line else 0,
+        stroke_style={"width": 2} if show_line else {"width": 0},
+        **kwargs,
+    )
+
+    # Set x-axis labels
+    x_values = data[x].tolist()
+    chart.x_labels = [str(val) for val in x_values]
+
+    # Add the data series
+    y_values = data[y].tolist()
+    series_label = ylabel or y
+    chart.add(series_label, y_values)
+
+    return chart
+
+
+if __name__ == "__main__":
+    # Sample data for testing - monthly website traffic
+    data = pd.DataFrame(
+        {
+            "Month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+            "Visitors": [12000, 15000, 18000, 22000, 25000, 28000, 30000, 32000, 29000, 26000, 23000, 20000],
+        }
+    )
+
+    # Create plot
+    chart = create_plot(
+        data,
+        x="Month",
+        y="Visitors",
+        title="Monthly Website Traffic",
+        xlabel="Month",
+        ylabel="Number of Visitors",
+        fill_alpha=0.5,
+        color="#2ecc71",
+    )
+
+    # Save as PNG
+    chart.render_to_png("plot.png")
+    print("Plot saved to plot.png")

specs/area-basic.md

@@ -4,52 +4,45 @@
 
 ## Description
 
-A basic area chart that displays quantitative data over a continuous interval or time period. The area between the line and the axis is filled with color, emphasizing the magnitude of values. Ideal for showing trends and cumulative totals over time.
+A basic area chart displays a single data series as a filled area under a line, connecting data points in sequence. This visualization is ideal for showing trends over time while emphasizing the magnitude of values through the filled region beneath the line.
 
 ## Data Requirements
 
-- **x**: Column for x-axis values (typically time or sequential data - numeric or datetime)
-- **y**: Numeric column for y-axis values (the values to be plotted)
+- **x**: Sequential values for the x-axis (numeric or categorical representing order/time)
+- **y**: Numeric values for the y-axis representing the magnitude at each point
 
 ## Optional Parameters
 
-- `title`: Plot title (default: None)
-- `xlabel`: X-axis label (default: uses column name)
-- `ylabel`: Y-axis label (default: uses column name)
-- `color`: Fill color for the area (default: library-specific default)
-- `alpha`: Transparency level for the fill (default: 0.5)
-- `line_color`: Color of the line at the top of the area (default: same as color but darker)
-- `line_width`: Width of the line (default: 2)
-- `fill_to`: What to fill to - 'zero' or 'none' (default: 'zero')
+- `title`: Chart title (type: str, default: None)
+- `xlabel`: X-axis label (type: str, default: column name)
+- `ylabel`: Y-axis label (type: str, default: column name)
+- `fill_alpha`: Transparency of the filled area (type: float, default: 0.5)
+- `color`: Color for the line and fill (type: str, default: library default)
+- `show_line`: Whether to show the line on top of fill (type: bool, default: True)
 
 ## Quality Criteria
 
-- [ ] X and Y axes are labeled with column names or custom labels
-- [ ] Area fill is visible but not overwhelming (appropriate alpha)
-- [ ] Line at top of area is clearly visible
-- [ ] Grid is visible but subtle (alpha <= 0.3)
-- [ ] No overlapping labels or tick marks
-- [ ] Data accurately represented without distortion
-- [ ] Appropriate figure size (16:9 aspect ratio)
+- [ ] X and Y axes are labeled with meaningful descriptions
+- [ ] The filled area is clearly visible with appropriate transparency (alpha ~0.5)
+- [ ] The line connecting data points is visible on top of the fill
+- [ ] Grid is present but subtle (alpha ≤ 0.5)
+- [ ] No overlapping axis labels or tick marks
+- [ ] Fill extends from the line to the baseline (y=0 or bottom axis)
+- [ ] Data points are accurately represented without distortion
 
 ## Expected Output
 
-A filled area chart with:
-- A colored area extending from the data line down to the x-axis (or zero line)
-- A visible line tracing the top of the area
-- Clear axis labels and optional title
-- Subtle grid for readability
-- Professional appearance suitable for presentations and reports
+A single area chart showing one data series with a filled region beneath the line. The line should be clearly visible on top of the semi-transparent fill. The fill should extend from the data line down to the x-axis baseline. The chart should include proper axis labels, a subtle grid for readability, and optionally a title. The overall appearance should be clean and professional, suitable for showing trends or cumulative data over a sequence.
 
 ## Tags
 
-area, line, trend, timeseries, basic, 2d
+area, trend, timeseries, basic, 2d, composition
 
 ## Use Cases
 
-- Visualizing stock price movements over time
-- Displaying website traffic trends
-- Showing cumulative sales or revenue over periods
-- Tracking temperature changes throughout the day
-- Monitoring resource usage (CPU, memory) over time
-- Displaying population growth trends
+- Visualizing website traffic over time with emphasis on volume
+- Showing cumulative sales or revenue trends over months/quarters
+- Displaying temperature variations throughout a day
+- Tracking stock price movements with visual volume emphasis
+- Monitoring system resource usage (CPU, memory) over time
+- Illustrating population growth or decline over years