feat(matplotlib): implement area-basic

plots/matplotlib/fill_between/area-basic/default.py

@@ -0,0 +1,126 @@
+"""
+area-basic: Basic Area Chart
+Implementation for: matplotlib
+Variant: default
+Python: 3.10+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+
+def create_plot(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    color: str = "steelblue",
+    alpha: float = 0.4,
+    line_color: Optional[str] = None,
+    line_width: float = 2.0,
+    title: Optional[str] = None,
+    xlabel: Optional[str] = None,
+    ylabel: Optional[str] = None,
+    figsize: tuple[float, float] = (16, 9),
+    **kwargs,
+) -> "Figure":
+    """
+    Create a basic area chart showing a filled region between the x-axis and a line.
+
+    Args:
+        data: Input DataFrame with required columns
+        x: Column name for x-axis values (continuous sequence)
+        y: Column name for y-axis values (numeric values)
+        color: Fill color for the area (default: "steelblue")
+        alpha: Transparency level for the filled area 0.0-1.0 (default: 0.4)
+        line_color: Color of the top edge line (default: same as fill color)
+        line_width: Width of the top edge line (default: 2.0)
+        title: Plot title (default: None)
+        xlabel: Custom x-axis label (default: column name)
+        ylabel: Custom y-axis label (default: column name)
+        figsize: Figure size as (width, height) (default: (16, 9))
+        **kwargs: Additional parameters passed to ax.fill_between()
+
+    Returns:
+        Matplotlib Figure 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]})
+        >>> fig = 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: {available}")
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=figsize)
+
+    # Get data values
+    x_values = data[x]
+    y_values = data[y]
+
+    # Determine line color (default to fill color if not specified)
+    edge_color = line_color if line_color else color
+
+    # Plot the filled area
+    ax.fill_between(x_values, y_values, alpha=alpha, color=color, **kwargs)
+
+    # Plot the top edge line for clarity
+    ax.plot(x_values, y_values, color=edge_color, linewidth=line_width)
+
+    # Apply styling
+    ax.set_xlabel(xlabel or x)
+    ax.set_ylabel(ylabel or y)
+    ax.grid(True, alpha=0.3, linestyle="--")
+
+    # Title
+    if title:
+        ax.set_title(title, fontsize=14, fontweight="bold")
+
+    # Tight layout to avoid label clipping
+    plt.tight_layout()
+
+    return fig
+
+
+if __name__ == "__main__":
+    # Sample data for testing - simulating 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, 32000, 30000, 27000, 24000, 20000, 18000],
+        }
+    )
+
+    # For a proper area chart, we need numeric x values
+    # Convert month names to numeric positions for continuous x-axis
+    data["Month_Num"] = range(1, 13)
+
+    # Create plot
+    fig = create_plot(
+        data, x="Month_Num", y="Visitors", title="Monthly Website Traffic", xlabel="Month", ylabel="Number of Visitors"
+    )
+
+    # Customize x-ticks to show month names
+    ax = fig.axes[0]
+    ax.set_xticks(range(1, 13))
+    ax.set_xticklabels(data["Month"])
+
+    # Save for inspection
+    plt.savefig("plot.png", dpi=300, bbox_inches="tight")
+    print("Plot saved to plot.png")

specs/area-basic.md

@@ -0,0 +1,63 @@
+# 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
+
+Create a simple area chart showing a filled region between the x-axis and a line.
+Perfect for visualizing quantities over continuous intervals, trends over time, or cumulative values.
+Works with any dataset containing a continuous x variable and numeric y values.
+
+## Data Requirements
+
+- **x**: Values for the x-axis (numeric or datetime: continuous sequence)
+- **y**: Numeric values defining the top of the filled area (numeric: continuous values)
+
+## Optional Parameters
+
+- `color`: Fill color for the area (type: string, default: "steelblue")
+- `alpha`: Transparency level for the filled area (type: float 0.0-1.0, default: 0.4)
+- `line_color`: Color of the top edge line (type: string, default: same as fill color)
+- `line_width`: Width of the top edge line (type: float, default: 2.0)
+- `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 if provided)
+- [ ] Grid is visible but subtle with alpha=0.3
+- [ ] Filled area is clearly visible with appropriate transparency
+- [ ] Top edge line is visible and distinguishes the data boundary
+- [ ] No overlapping axis labels or tick marks
+- [ ] Colorblind-safe colors (use accessible defaults)
+- [ ] Appropriate figure size (16x9 default) for readability
+- [ ] Title is centered and clearly readable if provided (fontsize 14, bold)
+
+## Expected Output
+
+A clean area chart with a filled region extending from the x-axis up to the data values.
+The filled area should have moderate transparency to show grid lines underneath while remaining clearly visible.
+A solid line along the top edge should clearly define where the data values lie.
+The plot should be immediately understandable without additional explanation.
+All text elements (labels, title, and tick labels) should be legible at standard display sizes.
+
+## Tags
+
+trend, continuous, basic, area, time-series, statistical, exploratory
+
+## Use Cases
+
+- Stock price visualization showing value over time (e.g., daily closing prices)
+- Website traffic metrics over time (e.g., daily page views)
+- Temperature variations throughout a day or season
+- Revenue or sales trends over months or years
+- Resource utilization over time (e.g., CPU usage, memory consumption)
+- Population growth over time periods