feat(bokeh): implement area-basic

plots/bokeh/varea/area-basic/default.py

@@ -0,0 +1,164 @@
+"""
+area-basic: Basic Area Chart
+Implementation for: bokeh
+Variant: default
+Python: 3.10+
+"""
+
+from typing import TYPE_CHECKING, Optional
+
+import pandas as pd
+from bokeh.models import ColumnDataSource
+from bokeh.plotting import figure
+
+
+if TYPE_CHECKING:
+    from bokeh.plotting import Figure
+
+
+def create_plot(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    fill_alpha: float = 0.5,
+    line_color: Optional[str] = None,
+    title: Optional[str] = None,
+    x_label: Optional[str] = None,
+    y_label: Optional[str] = None,
+    width: int = 1600,
+    height: int = 900,
+    **kwargs,
+) -> "Figure":
+    """
+    Create a basic filled area chart using bokeh.
+
+    A simple filled area chart showing a single data series over time or
+    sequential x-values. The area between the data line and the baseline
+    (zero) is filled with a semi-transparent color.
+
+    Args:
+        data: Input DataFrame with x and y columns
+        x: Column name for x-axis values
+        y: Column name for y-axis values
+        fill_alpha: Transparency of the filled area (default: 0.5)
+        line_color: Color of the line and fill (default: bokeh blue)
+        title: Chart title (optional)
+        x_label: Label for x-axis (optional, defaults to column name)
+        y_label: Label for y-axis (optional, defaults to column name)
+        width: Figure width in pixels (default: 1600)
+        height: Figure height in pixels (default: 900)
+        **kwargs: Additional parameters passed to figure
+
+    Returns:
+        Bokeh Figure object
+
+    Raises:
+        ValueError: If data is empty or fill_alpha is out of range
+        KeyError: If required columns not found
+
+    Example:
+        >>> data = pd.DataFrame({
+        ...     'Month': [1, 2, 3, 4, 5, 6],
+        ...     'Sales': [100, 120, 90, 140, 160, 130]
+        ... })
+        >>> fig = create_plot(data, x='Month', y='Sales', title='Monthly Sales')
+    """
+    # Input validation
+    if data.empty:
+        raise ValueError("Data cannot be empty")
+
+    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}")
+
+    if not 0 <= fill_alpha <= 1:
+        raise ValueError(f"fill_alpha must be between 0 and 1, got {fill_alpha}")
+
+    # Set default color (bokeh blue)
+    color = line_color or "#1f77b4"
+
+    # Sort data by x to ensure proper area rendering
+    plot_data = data[[x, y]].dropna().sort_values(by=x).reset_index(drop=True)
+
+    # Create ColumnDataSource
+    source = ColumnDataSource(data={"x": plot_data[x], "y": plot_data[y], "y0": [0] * len(plot_data)})
+
+    # Create figure
+    p = figure(
+        width=width,
+        height=height,
+        title=title or "Area Chart",
+        x_axis_label=x_label or x,
+        y_axis_label=y_label or y,
+        toolbar_location="above",
+        tools="pan,wheel_zoom,box_zoom,reset,save",
+        **kwargs,
+    )
+
+    # Draw the filled area from baseline (0) to y values
+    p.varea(x="x", y1="y0", y2="y", source=source, fill_color=color, fill_alpha=fill_alpha)
+
+    # Draw line on top for better visibility
+    p.line(x="x", y="y", source=source, line_color=color, line_width=2)
+
+    # Styling
+    p.title.text_font_size = "14pt"
+    p.title.align = "center"
+
+    # Grid styling - subtle
+    p.xgrid.grid_line_alpha = 0.3
+    p.ygrid.grid_line_alpha = 0.3
+    p.xgrid.grid_line_dash = [6, 4]
+    p.ygrid.grid_line_dash = [6, 4]
+
+    # Axis styling
+    p.xaxis.axis_label_text_font_size = "12pt"
+    p.yaxis.axis_label_text_font_size = "12pt"
+    p.xaxis.major_label_text_font_size = "10pt"
+    p.yaxis.major_label_text_font_size = "10pt"
+
+    return p
+
+
+if __name__ == "__main__":
+    import numpy as np
+
+    # Sample data: Monthly website traffic over a year
+    np.random.seed(42)
+    months = list(range(1, 13))
+    base_traffic = [1000, 1100, 1050, 1200, 1400, 1600, 1500, 1550, 1700, 1650, 1800, 2000]
+    noise = np.random.normal(0, 50, 12)
+    traffic = [max(0, int(b + n)) for b, n in zip(base_traffic, noise, strict=False)]
+
+    data = pd.DataFrame({"Month": months, "Visitors": traffic})
+
+    # Create plot
+    fig = create_plot(
+        data,
+        x="Month",
+        y="Visitors",
+        title="Monthly Website Traffic",
+        x_label="Month",
+        y_label="Visitors (thousands)",
+        fill_alpha=0.5,
+    )
+
+    # Save as PNG using webdriver-manager for automatic chromedriver
+    from bokeh.io import export_png
+    from selenium import webdriver
+    from selenium.webdriver.chrome.options import Options
+    from selenium.webdriver.chrome.service import Service
+    from webdriver_manager.chrome import ChromeDriverManager
+
+    chrome_options = Options()
+    chrome_options.add_argument("--headless")
+    chrome_options.add_argument("--no-sandbox")
+    chrome_options.add_argument("--disable-dev-shm-usage")
+
+    service = Service(ChromeDriverManager().install())
+    driver = webdriver.Chrome(service=service, options=chrome_options)
+
+    export_png(fig, filename="plot.png", webdriver=driver)
+    driver.quit()
+    print("Plot saved to plot.png")

specs/area-basic.md

@@ -1,56 +1,46 @@
 # 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 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.
+A simple filled area chart showing a single data series over time or sequential x-values. The area between the data line and the baseline (typically zero) is filled with a semi-transparent color to emphasize the magnitude of values.
 
 ## Data Requirements
 
-- **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)
+- **x**: Sequential or time-series values for the x-axis (numeric or datetime)
+- **y**: Numeric values to plot on the y-axis
 
 ## Optional Parameters
 
-- `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))
+- `fill_alpha`: Transparency of the filled area (type: float, default: 0.5)
+- `line_color`: Color of the line and fill (type: str, default: library default)
+- `title`: Chart title (type: str, default: None)
+- `x_label`: Label for x-axis (type: str, default: column name)
+- `y_label`: Label for y-axis (type: str, default: column name)
 
 ## 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
-- [ ] Area fill is clearly visible with appropriate transparency
-- [ ] Line on top of area provides clear boundary
+- [ ] X and Y axes are labeled with meaningful names
+- [ ] Grid is visible but subtle (alpha <= 0.5)
+- [ ] Area fill is semi-transparent (alpha between 0.3 and 0.7)
+- [ ] Line on top of fill area is visible
 - [ ] No overlapping axis labels or tick marks
-- [ ] Appropriate figure size (16:9 aspect ratio) for readability
-- [ ] Title is centered and clearly readable if provided
+- [ ] Data accurately represented without distortion
+- [ ] Figure has appropriate size (16:9 aspect ratio)
 
 ## Expected Output
 
-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.
+A clean area chart with a filled region between the data line and the x-axis baseline. The fill should be semi-transparent to allow grid lines to show through slightly. The line defining the top of the area should be clearly visible. Axes should be properly labeled, and a subtle grid should aid in reading values.
 
 ## Tags
 
-trend, time-series, basic, area, continuous, statistical, exploratory
+area, trend, time-series, basic, 2d
 
 ## Use Cases
 
-- 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
+- Visualizing website traffic over time
+- Showing cumulative sales or revenue trends
+- Displaying stock price history with emphasis on magnitude
+- Monitoring system resource usage over time
+- Tracking temperature or weather data trends