feat(plotnine): implement area-basic

Add basic area chart implementation for plotnine library.

- Creates spec file: specs/area-basic.md
- Creates implementation: plots/plotnine/area/area-basic/default.py
- Features: filled area with line overlay, customizable colors and transparency
- Uses geom_area() and geom_line() from plotnine
- Includes input validation, type hints, and Google-style docstrings

Author: github-actions[bot]

plots/plotnine/area/area-basic/default.py

@@ -0,0 +1,141 @@
+"""
+area-basic: Basic Area Chart
+Implementation for: plotnine
+Variant: default
+Python: 3.10+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
+import pandas as pd
+from plotnine import aes, element_line, element_text, geom_area, geom_line, ggplot, labs, theme, theme_minimal
+
+
+if TYPE_CHECKING:
+    from plotnine import ggplot as GGPlot
+
+
+def create_plot(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    title: Optional[str] = None,
+    xlabel: Optional[str] = None,
+    ylabel: Optional[str] = None,
+    color: str = "steelblue",
+    alpha: float = 0.6,
+    line_color: Optional[str] = None,
+    line_width: float = 1.5,
+    width: int = 16,
+    height: int = 9,
+    **kwargs,
+) -> "GGPlot":
+    """
+    Create a basic area chart showing values over a continuous axis using plotnine (ggplot2 syntax).
+
+    Args:
+        data: Input DataFrame with required columns
+        x: Column name for x-axis values (numeric or datetime)
+        y: Column name for y-axis values (numeric)
+        title: Plot title (optional)
+        xlabel: Custom x-axis label (optional, defaults to x column name)
+        ylabel: Custom y-axis label (optional, defaults to y column name)
+        color: Fill color for the area (default: 'steelblue')
+        alpha: Fill transparency level (default: 0.6)
+        line_color: Color of the top line (default: same as color)
+        line_width: Width of the top line (default: 1.5)
+        width: Figure width in inches (default: 16)
+        height: Figure height in inches (default: 9)
+        **kwargs: Additional parameters for geom_area
+
+    Returns:
+        plotnine ggplot object
+
+    Raises:
+        ValueError: If data is empty
+        KeyError: If required columns not found
+
+    Example:
+        >>> data = pd.DataFrame({
+        ...     'time': [1, 2, 3, 4, 5],
+        ...     'value': [10, 25, 15, 30, 20]
+        ... })
+        >>> plot = create_plot(data, x='time', y='value')
+    """
+    # 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}")
+
+    # Use the same color for line if not specified
+    if line_color is None:
+        line_color = color
+
+    # Sort data by x to ensure proper area rendering
+    data_sorted = data.sort_values(by=x).copy()
+
+    # Create the ggplot object with area and line
+    plot = (
+        ggplot(data_sorted, aes(x=x, y=y))
+        + geom_area(fill=color, alpha=alpha, **kwargs)
+        + geom_line(color=line_color, size=line_width)
+        + labs(title=title or "Area Chart", x=xlabel or x, y=ylabel or y)
+        + theme_minimal()
+        + theme(
+            figure_size=(width, height),
+            plot_title=element_text(size=14, weight="bold", ha="center"),
+            axis_title=element_text(size=11),
+            axis_text=element_text(size=10),
+            panel_grid_major=element_line(alpha=0.3, linetype="dashed"),
+            panel_grid_minor=element_line(alpha=0),
+        )
+    )
+
+    return plot
+
+
+if __name__ == "__main__":
+    # Sample data for testing - simulating time series data
+    np.random.seed(42)  # For reproducibility
+
+    # Generate sample time series data (e.g., monthly website visitors)
+    months = pd.date_range(start="2024-01-01", periods=12, freq="MS")
+
+    # Create realistic-looking growth pattern with some variation
+    base_values = np.linspace(1000, 2500, 12)
+    noise = np.random.normal(0, 150, 12)
+    values = base_values + noise
+
+    # Ensure no negative values
+    values = np.maximum(values, 100)
+
+    data = pd.DataFrame(
+        {
+            "Month": range(1, 13),  # Use numeric for simpler plotting
+            "Visitors": values,
+        }
+    )
+
+    # Create plot
+    plot = create_plot(
+        data,
+        x="Month",
+        y="Visitors",
+        title="Monthly Website Visitors (2024)",
+        xlabel="Month",
+        ylabel="Number of Visitors",
+        color="#3498db",
+        alpha=0.5,
+        line_color="#2980b9",
+        line_width=2,
+    )
+
+    # Save for inspection
+    plot.save("plot.png", dpi=300, verbose=False)
+    print("Plot saved to plot.png")

specs/area-basic.md

@@ -1,55 +1,56 @@
 # area-basic: Basic Area Chart
 
+<!--
+Spec Template Version: 1.0.0
+Created: 2025-12-01
+Last Updated: 2025-12-01
+-->
+
 **Spec Version:** 1.0.0
 
 ## 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.
+Create a simple area chart that displays a single filled area beneath a line, ideal for showing how a quantity changes over time or another continuous variable. The filled area emphasizes the magnitude of values and cumulative totals.
 
 ## 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**: Numeric or datetime column for the x-axis (continuous variable, typically time or sequence)
+- **y**: Numeric column for the y-axis (the values to plot)
 
 ## 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')
+- `color`: Fill color for the area (type: string, default: "steelblue")
+- `alpha`: Fill transparency level (type: float 0.0-1.0, default: 0.6)
+- `line_color`: Color of the top line (type: string, default: same as color)
+- `line_width`: Width of the top line (type: float, default: 1.5)
+- `title`: Plot title (type: string, default: None)
+- `xlabel`: Custom x-axis label (type: string, default: column name)
+- `ylabel`: Custom y-axis label (type: string, default: column name)
+- `figsize`: Figure size (type: tuple, default: (16, 9))
 
 ## 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 column names (or custom labels if provided)
+- [ ] Grid is visible but subtle with alpha=0.3
+- [ ] Area fill is clearly visible with appropriate transparency
+- [ ] Line on top of area provides clear boundary
+- [ ] No overlapping axis labels or tick marks
+- [ ] Appropriate figure size (16:9 aspect ratio) for readability
+- [ ] Title is centered and clearly readable if provided
 
 ## 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 clean area chart with a filled region showing values over a continuous axis. The area should be filled with a semi-transparent color, bounded by a line at the top edge. The baseline should be at y=0. Grid lines should help with reading values without overpowering the data. All text elements (labels, title, and tick labels) should be legible at standard display sizes.
 
 ## Tags
 
-area, line, trend, timeseries, basic, 2d
+trend, time-series, basic, area, continuous, statistical, exploratory
 
 ## 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
+- Stock price or market value over time (e.g., portfolio value growth)
+- Website traffic visualization (e.g., daily visitors over months)
+- Resource usage monitoring (e.g., CPU or memory usage over time)
+- Sales trends over time periods (e.g., monthly revenue)
+- Temperature or environmental data over time
+- Population growth or demographic changes