refast-echarts 0.1.0__py3-none-any.whl

refast_echarts/__init__.py

@@ -0,0 +1,64 @@
+"""Refast extension for ECharts
+
+Provides the ECharts component for Refast applications.
+"""
+
+from pathlib import Path
+
+from refast.extensions import Extension
+
+from .components import ECharts, Echarts
+
+
+class EchartsExtension(Extension):
+    """
+    ECharts extension for Refast.
+
+    Provides Apache ECharts integration with support for all chart types,
+    mouse events, theming, and dynamic updates via setOption.
+
+    Example:
+        ```python
+        from refast import RefastApp, Context
+        from refast_echarts import ECharts, EchartsExtension
+
+        ui = RefastApp(extensions=[EchartsExtension()])
+
+        @ui.page("/")
+        def home(ctx: Context):
+            return ECharts(
+                id="my-chart",
+                option={
+                    "xAxis": {"data": ["A", "B", "C"]},
+                    "yAxis": {},
+                    "series": [{"type": "bar", "data": [10, 20, 30]}]
+                },
+                on_click=ctx.callback(handle_click),
+                theme="light",
+                height="400px",
+            )
+        ```
+
+    For auto-discovery, install the package and it will be automatically loaded.
+    """
+
+    name = "refast-echarts"
+    version = "0.1.0"
+    description = "Refast extension for Apache ECharts"
+
+    # Static assets to load (relative to static_path)
+    scripts = ["refast-echarts.js"]
+    styles = []  # ECharts doesn't require external CSS
+
+    @property
+    def static_path(self) -> Path:
+        """Path to the static assets directory."""
+        return Path(__file__).parent / "static"
+
+    @property
+    def components(self) -> list:
+        """List of Python component classes provided by this extension."""
+        return [ECharts]
+
+
+__all__ = ["ECharts", "Echarts", "EchartsExtension"]

refast_echarts/components.py

@@ -0,0 +1,185 @@
+"""Component definitions for Refast extension for ECharts."""
+
+from typing import Any
+
+from refast.components.base import Component
+from refast.components.registry import register_component
+
+
+@register_component(
+    name="ECharts",
+    package="refast-echarts",
+    module="components",
+)
+class ECharts(Component):
+    """
+    Apache ECharts component for Refast.
+    
+    A powerful charting library that supports many chart types including
+    line, bar, pie, scatter, candlestick, map, and more.
+    
+    Args:
+        option: ECharts option configuration object.
+        theme: Theme name ('light', 'dark') or custom theme object.
+        init_opts: Initialization options for ECharts instance.
+        auto_resize: Whether to auto-resize chart when container size changes (default True).
+        width: Chart width (e.g., "100%", "600px"). If None, uses container width.
+        height: Chart height (e.g., "400px"). If None, uses container height.
+        loading: Whether to show loading animation.
+        loading_opts: Loading animation options.
+        
+        Event callbacks (all receive event data with chart interaction details):
+        on_click: Fired when clicking on a chart element.
+        on_dblclick: Fired when double-clicking on a chart element.
+        on_mousedown: Fired on mouse down.
+        on_mousemove: Fired on mouse move.
+        on_mouseup: Fired on mouse up.
+        on_mouseover: Fired when hovering over a chart element.
+        on_mouseout: Fired when mouse leaves a chart element.
+        on_globalout: Fired when mouse leaves the chart area entirely.
+        on_contextmenu: Fired on right-click context menu.
+        
+        id: Component ID (required for bound_js calls like setOption).
+        class_name: CSS classes to apply to the container.
+        style: Inline styles for the container.
+    
+    Bound Methods (callable via ctx.bound_js() or ctx.call_bound_js()):
+        setOption(option, notMerge=False, lazyUpdate=False): Update chart options.
+        resize(opts=None): Resize the chart.
+        clear(): Clear the chart.
+        showLoading(type='default', opts=None): Show loading animation.
+        hideLoading(): Hide loading animation.
+        getDataURL(opts=None): Get chart image as data URL.
+        dispose(): Dispose the chart instance.
+    
+    Example:
+        ```python
+        from refast import RefastApp, Context
+        from refast_echarts import ECharts
+        
+        ui = RefastApp()
+        
+        async def handle_click(ctx: Context):
+            data = ctx.event.data
+            print(f"Clicked: {data.get('name')}: {data.get('value')}")
+        
+        async def update_chart(ctx: Context):
+            new_option = {
+                "series": [{"data": [100, 200, 150, 80, 70]}]
+            }
+            await ctx.call_bound_js("my-chart", "setOption", new_option)
+        
+        @ui.page("/")
+        def home(ctx: Context):
+            return ECharts(
+                id="my-chart",
+                option={
+                    "title": {"text": "Sales Chart"},
+                    "xAxis": {"data": ["Mon", "Tue", "Wed", "Thu", "Fri"]},
+                    "yAxis": {},
+                    "series": [{"type": "bar", "data": [120, 200, 150, 80, 70]}]
+                },
+                on_click=ctx.callback(handle_click),
+                theme="light",
+                height="400px",
+            )
+        ```
+    """
+    
+    component_type = "ECharts"
+
+    def __init__(
+        self,
+        option: dict[str, Any] | None = None,
+        theme: str | dict[str, Any] | None = None,
+        init_opts: dict[str, Any] | None = None,
+        auto_resize: bool = True,
+        width: str | None = None,
+        height: str | None = None,
+        loading: bool = False,
+        loading_opts: dict[str, Any] | None = None,
+        # Mouse event callbacks
+        on_click: Any = None,
+        on_dblclick: Any = None,
+        on_mousedown: Any = None,
+        on_mousemove: Any = None,
+        on_mouseup: Any = None,
+        on_mouseover: Any = None,
+        on_mouseout: Any = None,
+        on_globalout: Any = None,
+        on_contextmenu: Any = None,
+        # Base props
+        id: str | None = None,
+        class_name: str = "",
+        style: dict[str, Any] | None = None,
+        **props: Any,
+    ):
+        super().__init__(id=id, class_name=class_name, **props)
+        self.option = option or {}
+        self.theme = theme
+        self.init_opts = init_opts
+        self.auto_resize = auto_resize
+        self.width = width
+        self.height = height
+        self.loading = loading
+        self.loading_opts = loading_opts
+        self.style = style or {}
+        
+        # Event callbacks
+        self.on_click = on_click
+        self.on_dblclick = on_dblclick
+        self.on_mousedown = on_mousedown
+        self.on_mousemove = on_mousemove
+        self.on_mouseup = on_mouseup
+        self.on_mouseover = on_mouseover
+        self.on_mouseout = on_mouseout
+        self.on_globalout = on_globalout
+        self.on_contextmenu = on_contextmenu
+
+    def _serialize_callback(self, callback: Any) -> dict | None:
+        """Serialize a callback if present."""
+        if callback is None:
+            return None
+        if hasattr(callback, 'serialize'):
+            return callback.serialize()
+        return callback
+
+    def render(self) -> dict[str, Any]:
+        style = {
+            **self.style,
+            **({"width": self.width} if self.width else {}),
+            **({"height": self.height} if self.height else {}),
+        }
+        # Exclude "style" from extra_props serialization since we build it above
+        extra = {k: v for k, v in self._serialize_extra_props().items() if k != "style"}
+
+        return {
+            "type": self.component_type,
+            "id": self.id,
+            "props": {
+                "option": self.option,
+                "theme": self.theme,
+                "init_opts": self.init_opts,
+                "auto_resize": self.auto_resize,
+                "loading": self.loading,
+                "loading_opts": self.loading_opts,
+                "style": style or None,
+                "class_name": self.class_name,
+                # Event callbacks
+                "on_click": self._serialize_callback(self.on_click),
+                "on_dblclick": self._serialize_callback(self.on_dblclick),
+                "on_mousedown": self._serialize_callback(self.on_mousedown),
+                "on_mousemove": self._serialize_callback(self.on_mousemove),
+                "on_mouseup": self._serialize_callback(self.on_mouseup),
+                "on_mouseover": self._serialize_callback(self.on_mouseover),
+                "on_mouseout": self._serialize_callback(self.on_mouseout),
+                "on_globalout": self._serialize_callback(self.on_globalout),
+                "on_contextmenu": self._serialize_callback(self.on_contextmenu),
+                **extra,
+            },
+            "children": self._render_children(),
+        }
+
+
+# Alias for backward compatibility
+Echarts = ECharts

refast_echarts-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: refast-echarts
+Version: 0.1.0
+Summary: Refast extension for ECharts
+Project-URL: Homepage, https://github.com/idling-mind/refast-echarts
+Project-URL: Bug Tracker, https://github.com/idling-mind/refast-echarts/issues
+Project-URL: Documentation, https://github.com/idling-mind/refast-echarts#readme
+Author-email: Najeem Muhammed <najeem@gmail.com>
+License-File: LICENSE
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.11
+Requires-Dist: refast>=0.0.8
+Description-Content-Type: text/markdown
+
+# refast-echarts
+
+Refast extension for ECharts
+
+A [Refast](https://github.com/idling-mind/refast) extension that provides the `Echarts` component.
+
+## Installation
+
+```bash
+pip install refast-echarts
+```
+
+## Usage
+
+### Option 1: Auto-Discovery (Recommended)
+
+When you install the package, Refast will automatically discover and load the extension:
+
+```python
+from fastapi import FastAPI
+from refast import RefastApp, Context
+from refast.components import Container
+from refast_echarts import ECharts
+
+ui = RefastApp(title="ECharts Demo")
+
+
+@ui.page("/")
+def home(ctx: Context):
+    option = {
+        "title": {"text": "Monthly Sales"},
+        "tooltip": {},
+        "xAxis": {
+            "data": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
+        },
+        "yAxis": {},
+        "series": [
+            {
+                "name": "Sales",
+                "type": "bar",
+                "data": [120, 200, 150, 80, 70, 110],
+            }
+        ],
+    }
+    return Container(
+        children=[
+            ECharts(option=option, height="400px"),
+        ]
+    )
+
+
+app = FastAPI()
+app.include_router(ui.router)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+### Option 2: Manual Registration
+
+If you want to disable auto-discovery and register extensions manually:
+
+```python
+from refast import RefastApp
+from refast_echarts import Echarts, EchartsExtension
+
+ui = RefastApp(
+    title="Echarts Demo",
+    auto_discover_extensions=False,
+    extensions=[EchartsExtension()],
+)
+```
+
+## Component Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `option` | dict | `{}` | ECharts option configuration object |
+| `theme` | str \| dict | `None` | Theme name (`"light"`, `"dark"`) or custom theme object |
+| `height` | str | `None` | Chart height (e.g. `"400px"`) |
+| `width` | str | `None` | Chart width (e.g. `"100%"`) |
+| `auto_resize` | bool | `True` | Auto-resize chart when container size changes |
+| `loading` | bool | `False` | Show loading animation |
+| `on_click` | Callback | `None` | Fired when clicking on a chart element |
+| `on_mouseover` | Callback | `None` | Fired when hovering over a chart element |
+| `id` | str | `None` | Component ID (required for `setOption` calls) |
+| `class_name` | str | `""` | CSS classes to apply to the container |
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- Node.js 18+
+- npm
+
+### Building the Frontend
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+This builds the UMD bundle to `src/refast_echarts/static/`.
+
+### Installing Locally
+
+```bash
+# Install with automatic frontend build (via hatch hook)
+pip install -e .
+
+# Or build frontend first, then install
+cd frontend && npm install && npm run build && cd ..
+pip install -e .
+```
+
+### Running the Example
+
+```bash
+python usage.py
+```
+
+Then open http://localhost:8000 in your browser.
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

refast_echarts-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+refast_echarts/__init__.py,sha256=CzstttVzp7cg9Y2J39AnH6-FEPrSjL4Dt7P43egXp0k,1770
+refast_echarts/components.py,sha256=d2tIc264ywRThMGjTEuEtFGBshF05PgaEb2tpD0VkZo,7046
+refast_echarts-0.1.0.dist-info/METADATA,sha256=7Qmagyfm6DpGg53NIm78NhPflwnNT0SVQHnpyRI5wDU,3922
+refast_echarts-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+refast_echarts-0.1.0.dist-info/entry_points.txt,sha256=kXhYVVapeEYp73-0A3YXsqfum9FdAtWoUxD6Xh9vdVM,62
+refast_echarts-0.1.0.dist-info/licenses/LICENSE,sha256=OY3qQlPXNv7ddTdyi2Qd_8rtMniF9sAMRjiaPtnbVJ8,1073
+refast_echarts-0.1.0.dist-info/RECORD,,

refast_echarts-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

refast_echarts-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[refast.extensions]
+echarts = refast_echarts:EchartsExtension

refast_echarts-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Najeem Muhammed
+
+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.
+