Introduce on_component_click for ui.echart (zauberzeug#5578)

### Motivation

Fix zauberzeug#5576, where in the case of clicking indicator label, all we have in
`e.args` is key `componentType` and `name`, causing library code to
throw an error.

But zauberzeug#5577 no good because it shoehorns the component click into point
click handler, which has a risk of breaking downstream user code
expecteding to take a point from the handler args.

### Implementation

We have to segregate: 

- All mandatory keys available for point click? Go to `on_point_click`
handler with `EChartPointClickEventArguments`
- Any else case, go to `on_component_click` handler with
`EChartComponentClickEventArguments`

### Progress

- [x] I chose a meaningful title that completes the sentence: "If
applied, this PR will..."
- [x] The implementation is complete.
- [x] Pytests have been added (or are not necessary).
- [x] Documentation has been added (or is not necessary).

---------

Co-authored-by: Falko Schindler <[email protected]>

Author: evnchn

nicegui/elements/echart/echart.js

@@ -22,7 +22,7 @@ export default {
     }
 
     this.chart = echarts.init(this.$el, theme_name, { renderer: this.renderer });
-    this.chart.on("click", (e) => this.$emit("pointClick", e));
+    this.chart.on("click", (e) => this.$emit("componentClick", e));
     for (const event of [
       "click",
       "dblclick",

nicegui/elements/echart/echart.py

@@ -5,7 +5,13 @@
 from ... import optional_features
 from ...awaitable_response import AwaitableResponse
 from ...element import Element
-from ...events import EChartPointClickEventArguments, GenericEventArguments, Handler, handle_event
+from ...events import (
+    EChartComponentClickEventArguments,
+    EChartPointClickEventArguments,
+    GenericEventArguments,
+    Handler,
+    handle_event,
+)
 
 try:
     from pyecharts.charts.base import default, json
@@ -22,6 +28,7 @@ class EChart(Element, component='echart.js', esm={'nicegui-echart': 'dist'}, def
     def __init__(self,
                  options: dict,
                  on_point_click: Optional[Handler[EChartPointClickEventArguments]] = None, *,
+                 on_click: Optional[Handler[EChartComponentClickEventArguments]] = None,
                  enable_3d: bool = False,
                  renderer: Literal['canvas', 'svg'] = 'canvas',
                  theme: Optional[Union[str, dict]] = None,
@@ -32,7 +39,8 @@ def __init__(self,
         Updates can be pushed to the chart by changing the `options` property.
 
         :param options: dictionary of EChart options
-        :param on_click_point: callback that is invoked when a point is clicked
+        :param on_point_click: callback that is invoked when a point is clicked
+        :param on_click: callback that is invoked when any component is clicked (*added in version 3.5.0*)
         :param enable_3d: enforce importing the echarts-gl library
         :param renderer: renderer to use ("canvas" or "svg", *added in version 2.7.0*)
         :param theme: an EChart theme configuration (dictionary or a URL returning a JSON object, *added in version 2.15.0*)
@@ -46,6 +54,8 @@ def __init__(self,
 
         if on_point_click:
             self.on_point_click(on_point_click)
+        if on_click:
+            self.on_click(on_click)
 
     def on_point_click(self, callback: Handler[EChartPointClickEventArguments]) -> Self:
         """Add a callback to be invoked when a point is clicked."""
@@ -65,7 +75,7 @@ def handle_point_click(e: GenericEventArguments) -> None:
                 data_type=e.args.get('dataType'),
                 value=e.args['value'],
             ))
-        self.on('pointClick', handle_point_click, [
+        self.on('componentClick', handle_point_click, [
             'componentType',
             'seriesType',
             'seriesIndex',
@@ -78,6 +88,21 @@ def handle_point_click(e: GenericEventArguments) -> None:
         ])
         return self
 
+    def on_click(self, callback: Handler[EChartComponentClickEventArguments]) -> Self:
+        """Add a callback to be invoked when any component is clicked."""
+        def handle_click(e: GenericEventArguments) -> None:
+            handle_event(callback, EChartComponentClickEventArguments(
+                sender=self,
+                client=self.client,
+                component_type=e.args['componentType'],
+                name=e.args.get('name'),
+            ))
+        self.on('componentClick', handle_click, [
+            'componentType',
+            'name',
+        ])
+        return self
+
     @classmethod
     def from_pyecharts(cls, chart: 'Chart', on_point_click: Optional[Callable] = None) -> Self:
         """Create an echart element from a pyecharts object.

nicegui/events.py

@@ -50,16 +50,22 @@ class SlideEventArguments(UiEventArguments):
     side: SlideSide
 
 
+@dataclass(**KWONLY_SLOTS)
+class EChartComponentClickEventArguments(UiEventArguments):
+    component_type: str
+    name: str | None
+
+
 @dataclass(**KWONLY_SLOTS)
 class EChartPointClickEventArguments(UiEventArguments):
     component_type: str
+    name: str
     series_type: str
     series_index: int
     series_name: str
-    name: str
     data_index: int
     data: float | int | str
-    data_type: str
+    data_type: str | None
     value: float | int | list
 
 

tests/test_echart.py

@@ -170,3 +170,37 @@ def page():
 
     screen.open('/')
     assert screen.find_by_tag('rect').value_of_css_property('fill') == 'rgb(254, 248, 239)'
+
+
+def test_click(screen: Screen):
+    events = []
+
+    @ui.page('/')
+    def page():
+        ui.echart({
+            'legend': {
+                'triggerEvent': True,
+            },
+            'radar': {
+                'triggerEvent': True,
+                'indicator': [{'name': name, 'max': 100} for name in ['A', 'B', 'C']],
+            },
+            'series': [{
+                'type': 'radar',
+                'data': [{'name': 'Test', 'value': [77.0, 50.0, 90.0]}],
+                'animation': False,
+            }],
+        }, on_point_click=lambda e: events.append(('point', e)), on_click=lambda e: events.append(('component', e))) \
+            .style('width: 200px; height: 200px')
+
+    screen.open('/')
+    echart = screen.find_by_tag('canvas')
+    for x, y in [(20, 20), (0, 70), (60, 30)]:
+        screen.click_at_position(echart, x, y)
+    screen.wait(0.5)
+    assert [(source, event.component_type, event.name) for source, event in events] == [
+        ('point', 'series', 'Test'),
+        ('component', 'series', 'Test'),
+        ('component', 'legend', None),
+        ('component', 'radar', 'C'),
+    ]

website/documentation/content/echart_documentation.py

@@ -34,6 +34,31 @@ def clickable_points() -> None:
     }, on_point_click=ui.notify)
 
 
+@doc.demo('EChart with clickable components', '''
+    Besides series points, you can register a callback for an event
+    when any component registered with `triggerEvent=True` is clicked.
+
+    Hint: Check if that component is a point by checking `e.component_type == 'series'`
+    to avoid double-processing with `on_point_click`.
+
+    *Added in version 3.5.0*
+''')
+def clickable_components() -> None:
+    ui.echart({
+        'legend': {
+            'triggerEvent': True,
+        },
+        'radar': {
+            'triggerEvent': True,
+            'indicator': [{'name': name, 'max': 100} for name in ['A', 'B', 'C']],
+        },
+        'series': [{
+            'type': 'radar',
+            'data': [{'name': 'Test', 'value': [77.0, 50.0, 90.0]}],
+        }],
+    }, on_click=ui.notify)
+
+
 @doc.demo('EChart with dynamic properties', '''
     Dynamic properties can be passed to chart elements to customize them such as apply an axis label format.
     To make a property dynamic, prefix a colon ":" to the property name.