feat(altair): implement area-basic

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

@@ -0,0 +1,158 @@
+"""
+area-basic: Basic Area Chart
+Implementation for: altair
+Variant: default
+Python: 3.10+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import altair as alt
+import pandas as pd
+
+
+if TYPE_CHECKING:
+    from altair import LayerChart
+
+
+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.7,
+    line_color: Optional[str] = None,
+    line_width: float = 2,
+    show_line: bool = True,
+    width: int = 800,
+    height: int = 450,
+    **kwargs,
+) -> "LayerChart":
+    """
+    Create a basic filled area chart showing a single data series using altair.
+
+    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: Transparency level for the fill (default: 0.7)
+        line_color: Color of the line at the top (default: same as fill color)
+        line_width: Width of the top line (default: 2)
+        show_line: Whether to show the line at the top (default: True)
+        width: Figure width in pixels (default: 800)
+        height: Figure height in pixels (default: 450)
+        **kwargs: Additional parameters for altair chart configuration
+
+    Returns:
+        Altair LayerChart object
+
+    Raises:
+        ValueError: If data is empty
+        KeyError: If required columns not found
+
+    Example:
+        >>> data = pd.DataFrame({
+        ...     'month': [1, 2, 3, 4, 5, 6],
+        ...     'sales': [100, 150, 200, 180, 220, 250]
+        ... })
+        >>> 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}")
+
+    # Determine encoding type for x-axis
+    x_dtype = data[x].dtype
+    if pd.api.types.is_datetime64_any_dtype(x_dtype):
+        x_encoding = f"{x}:T"
+    elif pd.api.types.is_numeric_dtype(x_dtype):
+        x_encoding = f"{x}:Q"
+    else:
+        x_encoding = f"{x}:O"
+
+    # Use provided line_color or default to fill color
+    actual_line_color = line_color if line_color is not None else color
+
+    # Create the area chart
+    area = (
+        alt.Chart(data)
+        .mark_area(
+            color=color,
+            opacity=alpha,
+            line={"color": actual_line_color, "strokeWidth": line_width} if show_line else False,
+        )
+        .encode(
+            x=alt.X(
+                x_encoding,
+                title=xlabel or x,
+                axis=alt.Axis(labelAngle=0 if len(data) <= 12 else -45, labelLimit=200),
+            ),
+            y=alt.Y(
+                f"{y}:Q",
+                title=ylabel or y,
+                scale=alt.Scale(domain=[0, data[y].max() * 1.1]),
+            ),
+            tooltip=[
+                alt.Tooltip(x_encoding, title=xlabel or x),
+                alt.Tooltip(f"{y}:Q", title=ylabel or y, format=",.2f"),
+            ],
+        )
+    )
+
+    # Configure the chart with title and styling
+    chart = area.properties(
+        width=width,
+        height=height,
+        title=alt.TitleParams(
+            text=title or "Area Chart",
+            fontSize=16,
+            anchor="middle",
+        ),
+    ).configure_view(
+        strokeWidth=0,
+    ).configure_axis(
+        grid=True,
+        gridOpacity=0.3,
+        gridDash=[3, 3],
+        domainWidth=1,
+        tickWidth=1,
+    )
+
+    return chart
+
+
+if __name__ == "__main__":
+    # Sample data for testing - monthly sales data
+    sample_data = pd.DataFrame({
+        "Month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+        "Sales": [120, 150, 180, 165, 200, 230, 250, 245, 220, 195, 170, 210],
+    })
+
+    # Create plot with ordinal x-axis
+    chart = create_plot(
+        sample_data,
+        x="Month",
+        y="Sales",
+        title="Monthly Sales Trend",
+        xlabel="Month",
+        ylabel="Sales ($K)",
+        color="steelblue",
+        alpha=0.7,
+    )
+
+    # Save as PNG
+    chart.save("plot.png", scale_factor=2.0)
+    print("Plot saved to plot.png")

specs/area-basic.md

@@ -0,0 +1,75 @@
+# area-basic: Basic Area Chart
+
+A simple filled area chart showing a single data series over time or sequential x-values, emphasizing the magnitude of values through the filled region below the line.
+
+## Data Requirements
+
+- **x**: Numeric or datetime column for x-axis values (sequential or time-based)
+- **y**: Numeric column for y-axis values (the area will be filled from zero to this value)
+
+## 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: "steelblue")
+- `alpha`: Transparency level for the fill (default: 0.7)
+- `line_color`: Color of the line at the top of the area (default: same as fill color)
+- `line_width`: Width of the top line (default: 2)
+- `show_line`: Whether to show the line at the top of the area (default: True)
+
+## Expected Output
+
+A filled area chart with:
+- X and Y axes labeled with column names (or custom labels)
+- Filled area from zero (baseline) to the data values
+- Optional line at the top edge of the filled area
+- Grid visible but subtle (alpha ≤ 0.3)
+- Professional appearance with proper spacing
+- Smooth visual representation of trends with emphasis on magnitude
+
+## Quality Criteria
+
+- [x] Axes labeled clearly
+- [x] Grid visible but subtle
+- [x] Fill area clearly visible with appropriate transparency
+- [x] No overlapping labels
+- [x] Appropriate figure size (16:9 aspect ratio)
+- [x] Type hints and validation present
+- [x] Colorblind-safe default color
+
+## Examples
+
+### Example 1: Basic Usage
+```python
+import pandas as pd
+data = pd.DataFrame({
+    'month': [1, 2, 3, 4, 5, 6],
+    'sales': [100, 150, 200, 180, 220, 250]
+})
+fig = create_plot(data, 'month', 'sales')
+```
+
+### Example 2: Custom Styling
+```python
+fig = create_plot(
+    data,
+    'month',
+    'sales',
+    alpha=0.5,
+    title='Monthly Sales Trend',
+    color='teal'
+)
+```
+
+## Use Cases
+
+- Visualizing cumulative values over time (e.g., total revenue growth)
+- Showing trends with emphasis on magnitude (e.g., stock prices)
+- Comparing values to a baseline (e.g., temperature variations from average)
+- Displaying time series data where the area under the curve is meaningful
+- Illustrating resource utilization over time (e.g., CPU usage)
+
+## Tags
+
+area, trend, time-series, basic, 2d