notecharts 0.1.0__py3-none-any.whl

notecharts/__init__.py

@@ -0,0 +1,5 @@
+from .widget import Chart, JSCode
+from .charts import Bar, Line, Scatter, Donut, Radar
+
+__version__ = "0.1.0"
+__all__ = ["Chart", "JSCode", "Bar", "Line", "Scatter", "Donut", "Radar"]

notecharts/charts.py

@@ -0,0 +1,841 @@
+import random
+import colorsys
+from .widget import Chart, JSCode
+
+def _format_data(data):
+    """Formats the input data for ECharts.
+
+    Args:
+        data (list-of-lists, list-of-dicts, or DataFrame): The input data.
+
+    Returns:
+        list: The formatted data.
+    """
+    if hasattr(data, "to_dict") and hasattr(data, "columns"):
+        return data.to_dict(orient="records")
+    return data
+
+def _deep_update(d, u):
+    """Recursively updates a dictionary.
+
+    Args:
+        d (dict): The dictionary to update.
+        u (dict): The update dictionary.
+    """
+    for k, v in u.items():
+        if isinstance(v, dict) and k in d and isinstance(d[k], dict):
+            _deep_update(d[k], v)
+        else:
+            d[k] = v
+
+def _get_harmony_hues(base_hue, harmony):
+    """Returns a list of hue angles for the given harmony scheme.
+
+    Args:
+        base_hue (float): Base hue angle (0-360).
+        harmony (str): Harmony scheme Name. One of 'monochromatic', 'complementary',
+            'triadic', 'tetradic', 'split-complementary', or 'analogous'.
+
+    Returns:
+        list[float]: List of hue angles.
+    """
+    base = base_hue % 360
+    if harmony == "monochromatic":
+        return [base]
+    elif harmony == "complementary":
+        return [base, (base + 180) % 360]
+    elif harmony == "triadic":
+        return [base, (base + 120) % 360, (base + 240) % 360]
+    elif harmony == "tetradic":
+        return [base, (base + 90) % 360, (base + 180) % 360, (base + 270) % 360]
+    elif harmony == "split-complementary":
+        return [base, (base + 150) % 360, (base + 210) % 360]
+    elif harmony == "analogous":
+        return [(base - 30) % 360, base, (base + 30) % 360]
+    else:
+        return [base]
+
+def _hsv_palette(n_colors, color_theme="pastel", base_hue=None, chart_theme="light", harmony="auto"):
+    """Generates a cohesive HEX color palette based on HSV values and harmonies.
+
+    Args:
+        n_colors (int): Number of colors to generate.
+        color_theme (str, optional): Preset saturation/value ('pastel', 'neon', 'professional').
+            Defaults to "pastel".
+        base_hue (float, optional): Seed hue (0-360). Defaults to None.
+        chart_theme (str, optional): 'light' or 'dark' background context. Defaults to "light".
+        harmony (str, optional): Color harmony scheme or 'auto'. Defaults to "auto".
+
+    Returns:
+        list[str]: List of HEX color strings.
+
+    Raises:
+        ValueError: If color_theme is unknown.
+    """
+    if n_colors <= 0:
+        return []
+
+    if chart_theme == "dark":
+        presets = {
+            "pastel":       (0.25, 0.90),
+            "neon":         (0.80, 0.95),
+            "professional": (0.45, 0.80),
+        }
+    else:
+        presets = {
+            "pastel":       (0.40, 0.80),
+            "neon":         (0.75, 1.00),
+            "professional": (0.50, 0.75),
+        }
+    if color_theme not in presets:
+        raise ValueError(f"Unknown color_theme '{color_theme}'. Choose from {list(presets.keys())}.")
+    sat, val = presets[color_theme]
+
+    if base_hue is None:
+        random.seed(42)
+        base_hue = random.random() * 360
+
+    # Auto-select harmony based on number of colors
+    if harmony == "auto":
+        if n_colors == 1:
+            harmony = "monochromatic"
+        elif n_colors == 2:
+            harmony = "complementary"
+        elif n_colors == 3:
+            harmony = "triadic"
+        elif n_colors == 4:
+            harmony = "tetradic"
+        elif n_colors == 5:
+            harmony = "split-complementary"
+        else:
+            harmony = "tetradic"
+
+    base_hues = _get_harmony_hues(base_hue, harmony)
+    colors = []
+    for i in range(n_colors):
+        if i < len(base_hues):
+            hue = base_hues[i]
+            s = sat
+            v = val
+        else:
+            # Generate variants by cycling through base hues and subtly altering sat/val
+            cycle = (i - len(base_hues)) // len(base_hues)
+            idx = (i - len(base_hues)) % len(base_hues)
+            hue = base_hues[idx]
+            # Alternate between slightly desaturated/lighter and slightly darkened
+            if cycle % 2 == 0:
+                s = sat * 0.85
+                v = min(1.0, val * 1.15)
+            else:
+                s = sat * 1.0
+                v = max(0.0, val * 0.85)
+        rgb = colorsys.hsv_to_rgb(hue / 360.0, s, v)
+        hex_color = "#{:02x}{:02x}{:02x}".format(
+            int(rgb[0] * 255), int(rgb[1] * 255), int(rgb[2] * 255)
+        )
+        colors.append(hex_color)
+    return colors
+
+class Bar(Chart):
+    """Pre-built modern Bar Chart.
+
+    Notecharts' Bar integration handles automatic layout, tooltips, and themes.
+    """
+
+    def __init__(
+        self,
+        data,
+        x,
+        y,
+        title=None,
+        width="99%",
+        height="500px",
+        renderer="canvas",
+        theme="light",
+        custom_options=None,
+        user_colors=None,
+        **kwargs
+    ):
+        """Initializes a Bar Chart.
+
+        Args:
+            data (list-of-lists, list-of-dicts, or DataFrame): The source data.
+            x (str): Column name for the x-axis.
+            y (str or list[str]): Column name(s) for the y-axis.
+            title (str, optional): Chart title. Defaults to None.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+            custom_options (dict, optional): Extra options to merge into the ECharts dict.
+            user_colors (list[str], optional): List of hex colors. Defaults to None.
+            **kwargs: Forwarded to the base Chart class.
+        """
+        formatted_data = _format_data(data)
+        y_cols = y if isinstance(y, list) else [y]
+
+        series = []
+        for y_col in y_cols:
+            series.append({
+                "type": "bar",
+                "encode": {"x": x, "y": y_col},
+                "name": str(y_col),
+                "itemStyle": {
+                    "borderRadius": [6, 6, 0, 0],
+                },
+                "animationDuration": 1200,
+                "animationEasing": "cubicOut",
+            })
+
+        # Use user-provided colors if given, else auto-generate harmonious palette
+        if user_colors is not None:
+            palette = user_colors
+        else:
+            palette = _hsv_palette(len(y_cols), color_theme="neon", chart_theme=theme, harmony="auto")
+
+        options = {
+            "color": palette,
+            "title": {
+                "text": title,
+                "left": "center",
+                "top": 24,
+                "textStyle": {
+                    "fontSize": 22,
+                    "fontWeight": 600,
+                },
+            },
+            "tooltip": {
+                "trigger": "axis",
+                "axisPointer": {"type": "shadow"},
+                "borderWidth": 0,
+                "padding": [14, 18],
+                "shadowBlur": 10,
+                "shadowColor": "rgba(0, 0, 0, 0.4)",
+                "shadowOffsetX": 0,
+                "shadowOffsetY": 4,
+                "extraCssText": "border-radius: 12px;"
+            },
+            "toolbox": {
+                "feature": {
+                    "restore": {},
+                    "magicType": {
+                        "type": ["line", "stack"]
+                    },
+                    "saveAsImage": {
+                        "name": title if title else "Chart"
+                    }
+                }
+            },
+            "dataZoom": {
+                "type": JSCode("'inside'")
+            },
+            "legend": {
+                "bottom": 20,
+                "type": "scroll",
+                "icon": "roundRect",
+                "textStyle": {"fontSize": 13},
+            },
+            "grid": {
+                "left": "5%",
+                "right": "5%",
+                "bottom": "18%",
+                "top": "18%",
+                "containLabel": True,
+            },
+            "xAxis": {
+                "type": "category",
+                "axisLine": {"show": False},
+                "axisTick": {"show": False},
+                "axisLabel": {"fontSize": 12},
+            },
+            "yAxis": {
+                "type": "value",
+                "splitLine": {
+                    "lineStyle": {
+                        "type": "dashed",
+                    }
+                },
+                "axisLabel": {"fontSize": 12},
+            },
+            "dataset": {"source": formatted_data},
+            "series": series,
+        }
+
+        if title is None:
+            del options["title"]
+
+        if custom_options:
+            _deep_update(options, custom_options)
+
+        super().__init__(
+            options=options,
+            width=width,
+            height=height,
+            renderer=renderer,
+            theme=theme,
+            **kwargs
+        )
+
+class Line(Chart):
+    """Pre-built modern Line Chart.
+
+    Supports smooth lines, area fill, and automatic color palettes.
+    """
+
+    def __init__(
+        self,
+        data,
+        x,
+        y,
+        title=None,
+        area=True,
+        smooth=True,
+        width="99%",
+        height="500px",
+        renderer="canvas",
+        theme="light",
+        custom_options=None,
+        user_colors=None,
+        **kwargs
+    ):
+        """Initializes a Line Chart.
+
+        Args:
+            data (list-of-lists, list-of-dicts, or DataFrame): The source data.
+            x (str): Column name for the x-axis.
+            y (str or list[str]): Column name(s) for the y-axis.
+            title (str, optional): Chart title. Defaults to None.
+            area (bool, optional): Whether to show area fill. Defaults to True.
+            smooth (bool, optional): Whether to smooth the line. Defaults to True.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+            custom_options (dict, optional): Extra options to merge into the ECharts dict.
+            user_colors (list[str], optional): List of hex colors. Defaults to None.
+            **kwargs: Forwarded to the base Chart class.
+        """
+        formatted_data = _format_data(data)
+        y_cols = y if isinstance(y, list) else [y]
+
+        if user_colors is not None:
+            palette = user_colors
+        else:
+            palette = _hsv_palette(len(y_cols), color_theme="neon", chart_theme=theme, harmony="auto")
+
+        series = []
+        for i, y_col in enumerate(y_cols):
+            color = palette[i % len(palette)]
+            ser = {
+                "type": "line",
+                "encode": {"x": x, "y": y_col},
+                "name": str(y_col),
+                "smooth": smooth,
+                "symbol": "circle",
+                "symbolSize": 8,
+                "lineStyle": {"width": 3},
+                "animationDuration": 1000,
+                "animationEasing": "cubicOut",
+            }
+            if area:
+                ser["areaStyle"] = {
+                    "color": {
+                        "type": "linear",
+                        "x": 0, "y": 0, "x2": 0, "y2": 1,
+                        "colorStops": [
+                            {"offset": 0, "color": f"{color}40"},
+                            {"offset": 1, "color": f"{color}00"}
+                        ]
+                    }
+                }
+            series.append(ser)
+
+        options = {
+            "color": palette,
+            "title": {
+                "text": title,
+                "left": "center",
+                "top": 24,
+                "textStyle": {"fontSize": 22, "fontWeight": 600},
+            },
+            "tooltip": {
+                "trigger": "axis",
+                "borderWidth": 0,
+                "padding": [14, 18],
+                "shadowBlur": 10,
+                "shadowColor": "rgba(0, 0, 0, 0.12)",
+                "extraCssText": "border-radius: 12px;",
+            },
+            "toolbox": {
+                "feature": {
+                    "restore": {},
+                    "magicType": {"type": ["bar", "stack"]},
+                    "saveAsImage": {
+                        "name": title if title else "Chart",
+                        "pixelRatio": 3
+                    },
+                    "dataZoom": {}
+                }
+            },
+            "dataZoom": {"type": JSCode("'inside'")},
+            "legend": {
+                "bottom": 20,
+                "type": "scroll",
+                "icon": "circle",
+                "textStyle": {"fontSize": 13},
+            },
+            "grid": {
+                "left": "5%",
+                "right": "5%",
+                "bottom": "18%",
+                "top": "18%",
+                "containLabel": True,
+            },
+            "xAxis": {
+                "type": "category",
+                "axisLine": {"show": False},
+                "axisTick": {"show": False},
+                "axisLabel": {"fontSize": 12},
+            },
+            "yAxis": {
+                "type": "value",
+                "splitLine": {"lineStyle": {"type": "dashed"}},
+                "axisLabel": {"fontSize": 12},
+            },
+            "dataset": {"source": formatted_data},
+            "series": series,
+        }
+
+        if title is None:
+            del options["title"]
+
+        if custom_options:
+            _deep_update(options, custom_options)
+
+        super().__init__(
+            options=options,
+            width=width,
+            height=height,
+            renderer=renderer,
+            theme=theme,
+            **kwargs
+        )
+
+class Scatter(Chart):
+    """Pre-built modern Scatter Plot.
+    
+    Optimized for high-density visualizations with clear tooltips.
+    """
+
+    def __init__(
+        self,
+        data,
+        x,
+        y,
+        title=None,
+        name_col=None,
+        width="99%",
+        height="500px",
+        renderer="canvas",
+        theme="light",
+        custom_options=None,
+        user_colors=None,
+        **kwargs
+    ):
+        """Initializes a Scatter Plot.
+
+        Args:
+            data (list-of-lists, list-of-dicts, or DataFrame): The source data.
+            x (str): Column name for the x-axis.
+            y (str or list[str]): Column name(s) for the y-axis.
+            title (str, optional): Chart title. Defaults to None.
+            name_col (str, optional): Column name for series names. Defaults to None.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+            custom_options (dict, optional): Extra options to merge into the ECharts dict.
+            user_colors (list[str], optional): List of hex colors. Defaults to None.
+            **kwargs: Forwarded to the base Chart class.
+        """
+        formatted_data = _format_data(data)
+        y_cols = y if isinstance(y, list) else [y]
+
+        series = []
+        for y_col in y_cols:
+            series.append({
+                "type": "scatter",
+                "encode": {"x": x, "y": y_col},
+                "name": str(y_col),
+                "symbolSize": 14,
+                "animationDuration": 1000,
+                "animationEasing": "cubicOut",
+            })
+
+        if user_colors is not None:
+            palette = user_colors
+        else:
+            palette = _hsv_palette(len(y_cols), color_theme="neon", chart_theme=theme, harmony="auto")
+
+        options = {
+            "color": palette,
+            "title": {
+                "text": title,
+                "left": "center",
+                "top": 24,
+                "textStyle": {"fontSize": 22, "fontWeight": 600},
+            },
+            "tooltip": {
+                "trigger": "item",
+                "borderWidth": 0,
+                "padding": [14, 18],
+                "shadowBlur": 10,
+                "shadowColor": "rgba(0, 0, 0, 0.12)",
+                "extraCssText": "border-radius: 12px;",
+                "formatter": JSCode(
+                    f"""function(params) {{
+                        var row = params.data;
+                        var lines = [];
+                        var nameVal = '{name_col}' ? row['{name_col}'] : null;
+                        if (nameVal !== undefined && nameVal !== null) {{
+                            lines.push('<strong>' + nameVal + '</strong>');
+                        }}
+                        var val, display;
+                        for (var key in row) {{
+                            if (row.hasOwnProperty(key) && key !== '{name_col}') {{
+                                val = row[key];
+                                display = (typeof val === 'number') ? val.toFixed(3) : val;
+                                lines.push(key + ': ' + display);
+                            }}
+                        }}
+                        return lines.join('<br/>');
+                    }}"""
+                )
+            },
+            "toolbox": {
+                "feature": {
+                    "restore": {},
+                    "saveAsImage": {
+                        "name": title if title else "Chart",
+                        "pixelRatio": 3
+                    },
+                    "dataZoom": {}
+                }
+            },
+            "dataZoom": {
+                "type": JSCode("'inside'")
+            },
+            "legend": {
+                "bottom": 20,
+                "type": "scroll",
+                "icon": "circle",
+                "textStyle": {"fontSize": 13},
+            },
+            "grid": {
+                "left": "5%",
+                "right": "5%",
+                "bottom": "18%",
+                "top": "18%",
+                "containLabel": True,
+            },
+            "xAxis": {
+                "type": "value",
+                "splitLine": {"lineStyle": {"type": "dashed"}},
+                "axisLabel": {"fontSize": 12},
+            },
+            "yAxis": {
+                "type": "value",
+                "splitLine": {"lineStyle": {"type": "dashed"}},
+                "axisLabel": {"fontSize": 12},
+            },
+            "dataset": {"source": formatted_data},
+            "series": series,
+        }
+
+        if title is None:
+            del options["title"]
+
+        if custom_options:
+            _deep_update(options, custom_options)
+
+        super().__init__(
+            options=options,
+            width=width,
+            height=height,
+            renderer=renderer,
+            theme=theme,
+            **kwargs
+        )
+
+class Donut(Chart):
+    """Pre-built modern Donut/Pie Chart.
+
+    Supports Nightingale Rose charts and automatic total label centering.
+    """
+
+    def __init__(
+        self,
+        data,
+        label_col,
+        value_col,
+        title=None,
+        rose=False,
+        show_total=True,
+        width="99%",
+        height="500px",
+        renderer="canvas",
+        theme="light",
+        custom_options=None,
+        user_colors=None,
+        **kwargs
+    ):
+        """Initializes a Donut Chart.
+
+        Args:
+            data (list-of-lists, list-of-dicts, or DataFrame): The source data.
+            label_col (str): Column name for slice labels.
+            value_col (str): Column name for slice values.
+            title (str, optional): Chart title. Defaults to None.
+            rose (bool, optional): Whether to use 'rose' type (Nightingale Chart). Defaults to False.
+            show_total (bool, optional): Whether to show the total value in the center. Defaults to True.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+            custom_options (dict, optional): Extra options to merge into the ECharts dict.
+            user_colors (list[str], optional): List of hex colors. Defaults to None.
+            **kwargs: Forwarded to the base Chart class.
+        """
+        formatted_data = _format_data(data)
+
+        pie_data = [{"name": str(row[label_col]), "value": row[value_col]} for row in formatted_data]
+
+        total = sum(row[value_col] for row in formatted_data)
+
+        series = {
+            "type": "pie",
+            "radius": ["45%", "75%"] if not rose else ["30%", "75%"],
+            "center": ["50%", "50%"],
+            "data": pie_data,
+            "label": {
+                "show": True,
+                "position": "outside",
+                "formatter": "{b}: {c} ({d}%)",
+                "fontSize": 12,
+            },
+            "emphasis": {
+                "label": {"fontSize": 16, "fontWeight": "bold"},
+                "scale": True,
+                "scaleSize": 10,
+            },
+            "animationType": "scale",
+            "animationEasing": "elasticOut",
+        }
+
+        if rose:
+            series["roseType"] = "radius"
+
+        graphic = None
+        if show_total and not rose:
+            graphic = [
+                {
+                    "type": "text",
+                    "left": "center",
+                    "top": "center",
+                    "style": {
+                        "text": f"{total}",
+                        "textAlign": "center",
+                        "fontSize": 24,
+                        "fontWeight": "bold",
+                        "fill": "#333" if theme == "light" else "#eee",
+                    },
+                }
+            ]
+
+        if user_colors is not None:
+            palette = user_colors
+        else:
+            palette = _hsv_palette(len(pie_data), color_theme="neon", chart_theme=theme, harmony="auto")
+
+        options = {
+            "color": palette,
+            "title": {
+                "text": title,
+                "left": "center",
+                "top": 24,
+                "textStyle": {"fontSize": 22, "fontWeight": 600},
+            },
+            # "tooltip": {
+            #     "trigger": "item",
+            #     "formatter": "{b}: {c} ({d}%)",
+            #     "borderWidth": 0,
+            #     "padding": [14, 18],
+            #     "shadowBlur": 10,
+            #     "shadowColor": "rgba(0, 0, 0, 0.12)",
+            #     "extraCssText": "border-radius: 12px;",
+            # },
+            "toolbox": {
+                "feature": {
+                    "restore": {},
+                    "saveAsImage": {
+                        "name": title if title else "Chart",
+                        "pixelRatio": 3
+                    },
+                }
+            },
+            "legend": {
+                "bottom": 20,
+                "type": "scroll",
+                "icon": "circle",
+                "textStyle": {"fontSize": 13},
+            },
+            "series": [series],
+        }
+
+        if graphic:
+            options["graphic"] = graphic
+
+        if title is None:
+            del options["title"]
+
+        if custom_options:
+            _deep_update(options, custom_options)
+
+        super().__init__(
+            options=options,
+            width=width,
+            height=height,
+            renderer=renderer,
+            theme=theme,
+            **kwargs
+        )
+
+class Radar(Chart):
+    """Pre-built modern Radar Chart.
+
+    Radar charts are ideal for displaying multivariate data on a 2D chart.
+    """
+
+    def __init__(
+        self,
+        data,
+        name_col,
+        dimensions,
+        title=None,
+        width="99%",
+        height="500px",
+        renderer="canvas",
+        theme="light",
+        custom_options=None,
+        user_colors=None,
+        **kwargs
+    ):
+        """Initializes a Radar Chart.
+
+        Args:
+            data (list-of-lists, list-of-dicts, or DataFrame): The source data.
+            name_col (str): Column that identifies each series (e.g., 'player').
+            dimensions (list[str]): Column names for the radar axes (e.g., ['speed', 'power']).
+            title (str, optional): Chart title. Defaults to None.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+            custom_options (dict, optional): Extra options to merge into the ECharts dict.
+            user_colors (list[str], optional): List of hex colors. Defaults to None.
+            **kwargs: Forwarded to the base Chart class.
+        """
+        formatted_data = _format_data(data)
+
+        # Group data by series name
+        series_map = {}
+        for row in formatted_data:
+            name = row[name_col]
+            series_map.setdefault(name, []).append(row)
+
+        # Compute max per dimension for indicator range
+        dim_max = {d: 0 for d in dimensions}
+        for row in formatted_data:
+            for d in dimensions:
+                if row[d] > dim_max[d]:
+                    dim_max[d] = row[d]
+
+        indicators = [{"name": d, "max": dim_max[d]} for d in dimensions]
+
+        # Build series list
+        series = []
+        for idx, (name, rows) in enumerate(series_map.items()):
+            row = rows[0]
+            values = [row[d] for d in dimensions]
+            series.append({
+                "type": "radar",
+                "data": [{"value": values, "name": str(name)}],
+                "areaStyle": {"opacity": 0.2},
+                "symbol": "circle",
+                "symbolSize": 6,
+                "lineStyle": {"width": 2},
+            })
+
+        if user_colors is not None:
+            palette = user_colors
+        else:
+            palette = _hsv_palette(len(series), color_theme="neon", chart_theme=theme, harmony="auto")
+
+        options = {
+            "color": palette,
+            "title": {
+                "text": title,
+                "left": "center",
+                "top": 24,
+                "textStyle": {"fontSize": 22, "fontWeight": 600},
+            },
+            "tooltip": {
+                "trigger": "item",
+                "borderWidth": 0,
+                "padding": [14, 18],
+                "shadowBlur": 10,
+                "shadowColor": "rgba(0, 0, 0, 0.12)",
+                "extraCssText": "border-radius: 12px;",
+            },
+            "toolbox": {
+                "feature": {
+                    "restore": {},
+                    "saveAsImage": {
+                        "name": title if title else "Chart",
+                        "pixelRatio": 3
+                    },
+                }
+            },
+            "legend": {
+                "bottom": 20,
+                "type": "scroll",
+                "icon": "circle",
+                "textStyle": {"fontSize": 13},
+            },
+            "radar": {
+                "indicator": indicators,
+                "splitArea": {
+                    "areaStyle": {
+                        "color": ["rgba(0,0,0,0.02)", "rgba(0,0,0,0.04)"]
+                    }
+                },
+                "axisLine": {"lineStyle": {"color": "rgba(0,0,0,0.1)"}},
+                "splitLine": {"lineStyle": {"color": "rgba(0,0,0,0.1)"}},
+            },
+            "series": series,
+        }
+
+        if title is None:
+            del options["title"]
+
+        if custom_options:
+            _deep_update(options, custom_options)
+
+        super().__init__(
+            options=options,
+            width=width,
+            height=height,
+            renderer=renderer,
+            theme=theme,
+            **kwargs
+        )

notecharts/widget.py

@@ -0,0 +1,283 @@
+import json
+import uuid
+import urllib.parse
+from IPython.display import display, HTML
+
+
+class JSCode:
+    """Wraps a raw JavaScript string to be inserted unquoted into the ECharts options.
+
+    Attributes:
+        js (str): The raw JavaScript code string.
+    """
+    def __init__(self, js: str):
+        """Initializes JSCode with the given JavaScript string.
+
+        Args:
+            js (str): The JavaScript code.
+        """
+        self.js = js
+
+    def __repr__(self):
+        return f"JSCode({self.js!r})"
+
+
+class _EChartsEncoder(json.JSONEncoder):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.placeholders = {}
+
+    def default(self, obj):
+        if isinstance(obj, JSCode):
+            placeholder = f"__JS_{uuid.uuid4().hex}__"
+            self.placeholders[placeholder] = obj.js
+            return placeholder
+        return super().default(obj)
+
+
+class Chart:
+    """Renders Apache ECharts directly in a Jupyter notebook from a Python 'options' dict.
+
+    Features include automatic Google Fonts loading from any 'fontFamily' value found
+    inside the options dictionary and global font setting via `textStyle.fontFamily`.
+
+    Attributes:
+        options (dict): The ECharts option dictionary.
+        width (str): CSS width of the chart container.
+        height (str): CSS height of the chart container.
+        renderer (str): The renderer type ('canvas' or 'svg').
+        theme (str): The chart theme ('light' or 'dark').
+        fonts (list): List of discovered custom font families.
+    """
+
+    # Generic CSS font families that should not be loaded from Google Fonts
+    _GENERIC_FONTS = {
+        "serif", "sans-serif", "monospace", "cursive", "fantasy",
+        "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace",
+        "ui-rounded", "math", "emoji", "fangsong",
+        "inherit", "initial", "unset"
+    }
+
+    def __init__(
+        self,
+        options: dict,
+        width: str = "99%",
+        height: str = "500px",
+        renderer: str = "canvas",
+        theme: str = "light",
+    ):
+        """Initializes the Chart with options and display settings.
+
+        Args:
+            options (dict): The ECharts option dictionary.
+            width (str, optional): CSS width. Defaults to "99%".
+            height (str, optional): CSS height. Defaults to "500px".
+            renderer (str, optional): 'canvas' or 'svg'. Defaults to "canvas".
+            theme (str, optional): 'light' or 'dark'. Defaults to "light".
+
+        Raises:
+            TypeError: If options is not a dictionary.
+            ValueError: If renderer or theme is invalid.
+        """
+        if not isinstance(options, dict):
+            raise TypeError(
+                f"Chart options must be a dictionary, got {type(options).__name__}."
+            )
+        self.options = options
+        self.width = width.strip() if isinstance(width, str) else str(width)
+        self.height = height.strip() if isinstance(height, str) else str(height)
+
+        self.renderer = renderer.lower().strip()
+        if self.renderer not in ["canvas", "svg"]:
+            raise ValueError(
+                f"Invalid renderer '{self.renderer}'. Supported: 'canvas', 'svg'."
+            )
+
+        self.theme = theme.lower().strip()
+        if self.theme not in ["light", "dark"]:
+            raise ValueError(
+                f"Invalid theme '{self.theme}'. Supported: 'light', 'dark'."
+            )
+
+        if self.theme == "light" and "backgroundColor" not in self.options:
+            self.options["backgroundColor"] = "white"
+
+        # Discover all custom font families from the options dict
+        self.fonts = list(self._discover_fonts(self.options))
+
+    # ------------------------------------------------------------------
+    # Font discovery
+    # ------------------------------------------------------------------
+    @classmethod
+    def _extract_font_families(cls, value):
+        """Return a set of non‑generic font family names from a raw value."""
+        if isinstance(value, JSCode):
+            return set()
+        if isinstance(value, str):
+            candidates = [name.strip().strip("'\"") for name in value.split(",")]
+        elif isinstance(value, (list, tuple)):
+            candidates = []
+            for item in value:
+                if isinstance(item, str):
+                    candidates.extend(
+                        name.strip().strip("'\"") for name in item.split(",")
+                    )
+        else:
+            return set()
+
+        families = set()
+        for candidate in candidates:
+            lower = candidate.lower()
+            # Keep only non‑generic names
+            if lower and lower not in cls._GENERIC_FONTS:
+                families.add(candidate)
+        return families
+
+    def _discover_fonts(self, obj, found=None):
+        """Recursively walk the options dict to collect font families."""
+        if found is None:
+            found = set()
+        if isinstance(obj, dict):
+            for key, value in obj.items():
+                if key == "fontFamily":
+                    found.update(self._extract_font_families(value))
+                else:
+                    self._discover_fonts(value, found)
+        elif isinstance(obj, list):
+            for item in obj:
+                self._discover_fonts(item, found)
+        return found
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+    def _serialise_options(self) -> str:
+        encoder = _EChartsEncoder()
+        json_str = encoder.encode(self.options)
+        for placeholder, js_code in encoder.placeholders.items():
+            json_str = json_str.replace(f'"{placeholder}"', js_code)
+        return json_str
+
+    # ------------------------------------------------------------------
+    # HTML generation
+    # ------------------------------------------------------------------
+    def _make_chart_html(self, chart_id=None) -> str:
+        if chart_id is None:
+            chart_id = f"echart_{uuid.uuid4().hex}"
+        options_js = self._serialise_options()
+
+        font_link = ""
+        if self.fonts:
+            base_url = "https://fonts.googleapis.com/css2"
+            params = {"family": self.fonts, "display": "swap"}
+            query_string = urllib.parse.urlencode(params, doseq=True)
+            font_link = f'<link href="{base_url}?{query_string}" rel="stylesheet">'
+
+        has_fonts = "true" if self.fonts else "false"
+
+        return f"""
+        {font_link}
+        <div id="{chart_id}" style="width:{self.width};height:{self.height};"></div>
+        <script>
+        (function() {{
+
+            // ── wait for the div to exist in the DOM ──────────────────────────
+            function waitForDom(id, cb) {{
+                var dom = document.getElementById(id);
+                if (dom) {{ cb(dom); return; }}
+                var observer = new MutationObserver(function() {{
+                    var el = document.getElementById(id);
+                    if (el) {{ observer.disconnect(); cb(el); }}
+                }});
+                observer.observe(document.body || document.documentElement, {{
+                    childList: true, subtree: true
+                }});
+                var attempts = 0;
+                var poll = setInterval(function() {{
+                    var el = document.getElementById(id);
+                    if (el) {{ clearInterval(poll); observer.disconnect(); cb(el); return; }}
+                    if (++attempts > 100) {{
+                        clearInterval(poll); observer.disconnect();
+                        console.error('ECharts wrapper: #{chart_id} never appeared in DOM');
+                    }}
+                }}, 100);
+            }}
+
+            // ── chart init ─────
+            function initChart(ec) {{
+                waitForDom('{chart_id}', function(dom) {{
+                    var chart = ec.init(dom, '{self.theme}', {{
+                        renderer: '{self.renderer}', devicePixelRatio: 3
+                    }});
+                    chart.setOption({options_js});
+                    window.addEventListener('resize', function() {{ chart.resize(); }});
+                }});
+            }}
+
+            // ── plain <script> loader (Colab / plain Jupyter) ─────────────────
+            function loadScript(url, cb) {{
+                var s = document.createElement('script');
+                s.src = url;
+                s.onload = cb;
+                s.onerror = function() {{ console.error('ECharts wrapper: failed to load ' + url); }};
+                document.head.appendChild(s);
+            }}
+
+            function loadViaScript() {{
+                loadScript('https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js', function() {{
+                    loadScript('https://cdn.jsdelivr.net/npm/echarts-gl/dist/echarts-gl.min.js', function() {{
+                        initChart(window.echarts);
+                    }});
+                }});
+            }}
+
+            // ── RequireJS loader (VS Code webview) ────────────────────────────
+            function loadViaRequire() {{
+                // Reset any cached failed/partial module state
+                require.undef('echarts');
+                require.undef('echarts-gl');
+                require.config({{
+                    paths: {{
+                        'echarts': 'https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min',
+                        'echarts-gl': 'https://cdn.jsdelivr.net/npm/echarts-gl/dist/echarts-gl.min'
+                    }}
+                }});
+                require(['echarts'], function(ec) {{
+                    require(['echarts-gl'], function() {{
+                        initChart(ec);
+                    }});
+                }}, function(err) {{
+                    console.error('ECharts wrapper: RequireJS failed to load', err);
+                }});
+            }}
+
+            // ── font gate → then load echarts ─────────────────────────────────
+            function loadEchartsAndInit() {{
+                if (typeof require !== 'undefined' && typeof require.config === 'function') {{
+                    loadViaRequire();
+                }} else {{
+                    loadViaScript();
+                }}
+            }}
+
+            if ({has_fonts}) {{
+                if (document.fonts && document.fonts.ready) {{
+                    document.fonts.ready.then(loadEchartsAndInit);
+                }} else {{
+                    loadEchartsAndInit();
+                }}
+            }} else {{
+                loadEchartsAndInit();
+            }}
+        }})();
+        </script>
+        """
+
+    # ------------------------------------------------------------------
+    # Display
+    # ------------------------------------------------------------------
+    def display(self):
+        display(HTML(self._make_chart_html()))
+
+    def _repr_html_(self):
+        return self._make_chart_html()

notecharts-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: notecharts
+Version: 0.1.0
+Summary: Beautiful, interactive charts in notebooks with Apache ECharts' powerful declarative API
+Author-email: Danish Munib <danishmunibcontact@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dmunish/notecharts
+Project-URL: Repository, https://github.com/dmunish/notecharts.git
+Project-URL: Issues, https://github.com/dmunish/notecharts/issues
+Keywords: echarts,jupyter,visualization,charts,notebook
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: IPython
+Dynamic: license-file
+
+# notecharts
+
+[![PyPI version](https://img.shields.io/pypi/v/notecharts.svg?style=flat-square)](https://pypi.org/project/notecharts/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Python Versions](https://img.shields.io/pypi/pyversions/notecharts.svg?style=flat-square)](https://pypi.org/project/notecharts/)
+
+**notecharts** is an ultra-lightweight, zero-config wrapper for Apache ECharts in Jupyter environments. It brings the full power of ECharts' declarative JSON-like API directly into Python notebooks without the bloat.
+
+## Why notecharts?
+
+If you've used ECharts in Python before, you likely encountered two extremes:
+- **pyecharts:** Powerful, but wraps the API in a deep "Pythonic" abstraction that often deviates from the official ECharts documentation, making it hard to translate JS examples to Python.
+- **ipecharts:** Often lacks the interactivity or ease of use, API is buggy or unclear sometimes.
+
+**notecharts** bridges this gap. It provides a thin layer that allows you to write ECharts options exactly as they appear in the official docs, while handling the heavy lifting of library loading, font injection, and serialization.
+
+## Key Features
+
+- **Declarative API:** Pass a dictionary, get a chart. No complex class hierarchies to learn.
+- **`JSCode` Support:** Inject raw JavaScript functions for formatters, tooltips, and custom logic.
+- **Smart Font Discovery:** Automatically detect `fontFamily` declarations in your options fetch the corresponding fonts (if available) from Google Fonts.
+- **Pre-built Modern Charts:** Includes high-level classes like `Bar`, `Line`, `Scatter`, `Donut`, and `Radar` with beautiful default harmonies.
+- **Environment Agnostic:** Works seamlessly in VS Code, JupyterLab, and Google Colab.
+
+## Installation
+
+```bash
+pip install notecharts
+```
+
+## Usage
+
+### The Declarative Way (Total Control)
+If you can find an example on the [ECharts Gallery](https://echarts.apache.org/examples/en/index.html), you can run it in `notecharts`.
+
+```python
+from notecharts import Chart, JSCode
+
+options = {
+    "title": {"text": "Basic Chart"},
+    "xAxis": {"data": ["Mon", "Tue", "Wed", "Thu", "Fri"]},
+    "yAxis": {},
+    "series": [{
+        "type": "bar",
+        "data": [23, 24, 18, 25, 27], # or any other object/variable
+        "label": {
+            "show": True,
+            "formatter": JSCode("function(p) { return p.value + ' units'; }")
+        }
+    }],
+    "textStyle": {
+        "fontFamily": "Inter" # Automatically loaded from Google Fonts!
+    }
+}
+
+Chart(options).display()
+```
+
+### The Quick Way (Pre-built Charts)
+Use the pre-configured classes for common visualizations with aesthetic defaults.
+
+```python
+import pandas as pd
+from notecharts import Bar
+
+df = pd.DataFrame({                 # or a list-of-lists, list-of-dicts format
+    "Day": ["Mon", "Tue", "Wed"],
+    "Sales": [150, 230, 224]
+})
+
+Bar(df, x="Day", y="Sales", title="Weekly Sales", theme="dark").display()
+```
+
+## Important Considerations
+
+- **Security:** Use of `JSCode` allows for arbitrary JavaScript execution in the browser/notebook context. Always ensure you are passing trusted code and data to your charts.
+- **Connectivity:** This library is ultra-lightweight because it does not ship with the ECharts binaries. It fetches them from `cdn.jsdelivr.net` at runtime, so an active internet connection is required to render charts.
+
+## License & Attribution
+
+- **notecharts** is licensed under the [MIT License](LICENSE).
+- **Apache ECharts**: This library is a wrapper for [Apache ECharts](https://echarts.apache.org/en/index.html) (incubating), which is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). 
+  - *Apache ECharts, ECharts, Apache, the Apache feather, and the Apache ECharts project logo are either registered trademarks or trademarks of the Apache Software Foundation.*
+
+## References
+See the [ECharts gallery](https://echarts.apache.org/examples/en/index.html) for bespoke examples, or the [official docs](https://echarts.apache.org/en/option.html) for an in-depth exaplanation of the options available.

notecharts-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+notecharts/__init__.py,sha256=h1VZfPx-fHwLo2l0iP9SSEe0Vci4_03tAAq5Bzlr9mM,187
+notecharts/charts.py,sha256=eg0j1tEqpGmzWpkaliM7gCr3t87yiB0ZgCwjyQh10sk,28760
+notecharts/widget.py,sha256=ZtVmdwLHHSv8KvA2g6htuT_Ao7SPBP0lCntmDklIfQA,11513
+notecharts-0.1.0.dist-info/licenses/LICENSE,sha256=yANfqZOnU8lIR8tMZUb-OXpgyLGc45Ylj2bMo7tT5P8,1090
+notecharts-0.1.0.dist-info/licenses/NOTICE,sha256=vo0eaMGEOBbYs5ItJDuBH47ICpXVkRe0bcRoDCrbj7Y,217
+notecharts-0.1.0.dist-info/METADATA,sha256=ndjPBnTw1D3cUa4rsWkE2_8oRh7-rh6te3jAoEgFPpQ,5149
+notecharts-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+notecharts-0.1.0.dist-info/top_level.txt,sha256=3jxe7NoyPdB9lCntHLeaMWsTh-5KDCBjkQKE7C5R77o,11
+notecharts-0.1.0.dist-info/RECORD,,

notecharts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

notecharts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danish Munib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

notecharts-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,8 @@
+notecharts
+Copyright 2026 Danish Munib
+
+This product includes software developed at
+The Apache Software Foundation (https://www.apache.org/).
+
+Apache ECharts
+Copyright 2017-2026 The Apache Software Foundation

notecharts-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+notecharts