Merge branch 'main' into ahmad/react-flow-docs

Author: LineIndent

docs/wrapping-react/props.md

@@ -154,4 +154,49 @@ class EventHandlerComponent(MyBaseComponent):
 
 ```md alert info
 # Custom event specs have a few use case where they are particularly useful. If the event returns non-serializable data, you can filter them out so the event can be sent to the backend. You can also use them to transform the data before sending it to the backend.
+```
+
+### Emulating Event Handler Behavior Outside a Component
+
+In some instances, you may need to replicate the special behavior applied to
+event handlers from outside of a component context. For example if the component
+to be wrapped requires event callbacks passed in a dictionary, this can be
+achieved by directly instantiating an `EventChain`.
+
+A real-world example of this is the `onEvents` prop of
+[`echarts-for-react`](https://www.npmjs.com/package/echarts-for-react) library,
+which, unlike a normal event handler, expects a mapping of event handlers like:
+
+```javascript
+<ReactECharts
+  option={this.getOption()}
+  style={{ height: '300px', width: '100%' }}
+  onEvents={{
+    'click': this.onChartClick,
+    'legendselectchanged': this.onChartLegendselectchanged
+  }}
+/>
+```
+
+To achieve this in Reflex, you can create an explicit `EventChain` for each
+event handler:
+
+```python
+@classmethod
+def create(cls, *children, **props):
+    on_events = props.pop("on_events", {})
+
+    event_chains = {}
+    for event_name, handler in on_events.items():
+        # Convert the EventHandler/EventSpec/lambda to an EventChain
+        event_chains[event_name] = rx.EventChain.create(
+            handler,
+            args_spec=rx.event.no_args_event_spec,
+            key=event_name,
+        )
+    if on_events:
+        props["on_events"] = event_chains
+
+    # Create the component instance
+    return super().create(*children, **props)
 ```

pcweb/pages/docs/apiref.py

@@ -9,7 +9,7 @@
     rx.Base,
     rx.Component,
     rx.ComponentState,
-    rx.Config,
+    (rx.Config, rx.config.BaseConfig),
     rx.event.Event,
     rx.event.EventHandler,
     rx.event.EventSpec,
@@ -26,9 +26,17 @@
 
 pages = []
 for module in modules:
+    if isinstance(module, tuple):
+        module, *extra_modules = module
+        extra_fields = []
+        for extra_module in extra_modules:
+            s_extra = Source(module=extra_module)
+            extra_fields.extend(s_extra.get_fields())
+    else:
+        extra_fields = None
     s = Source(module=module)
     name = module.__name__.lower()
-    docs = generate_docs(name, s)
+    docs = generate_docs(name, s, extra_fields=extra_fields)
     title = name.replace("_", " ").title()
     page_data = docpage(f"/docs/api-reference/{name}/", title)(docs)
     page_data.title = page_data.title.split("·")[0].strip()

pcweb/pages/docs/source.py

@@ -1,8 +1,9 @@
+import dataclasses
 import inspect
 import re
 
 # Get the comment for a specific field.
-from typing import Callable, Type
+from typing import Callable, ClassVar, Type, get_origin, get_type_hints
 
 import reflex as rx
 from pcweb.templates.docpage import h1_comp, h2_comp
@@ -54,9 +55,11 @@ def get_class_fields(self) -> list[dict]:
         return out
 
     def get_fields(self) -> list[dict]:
-        if not issubclass(self.module, rx.Base):
-            return []
-        return self.get_annotations(self.module.__fields__)
+        if dataclasses.is_dataclass(self.module):
+            return self.get_annotations({f.name: f for f in dataclasses.fields(self.module)})
+        elif isinstance(self.module, type) and issubclass(self.module, rx.Base):
+            return self.get_annotations(self.module.__fields__)
+        return []
 
     def get_methods(self):
         return [
@@ -170,8 +173,16 @@ def get_annotations(self, props) -> list[dict]:
 
 
 def format_field(field):
-    type_ = field["prop"].type_
+    prop = field["prop"]
+    try:
+        type_ = prop.type_
+    except AttributeError:
+        type_ = prop.type
     default = field["prop"].default
+    if default is dataclasses.MISSING:
+        default = None
+    else:
+        default = repr(default)
     type_str = type_.__name__ if hasattr(type_, "__name__") else str(type_)
     if default:
         type_str += f" = {default}"
@@ -217,8 +228,10 @@ def format_fields(headers, fields):
     )
 
 
-def generate_docs(title: str, s: Source):
+def generate_docs(title: str, s: Source, extra_fields: list[dict] | None = None):
     fields = s.get_fields()
+    if extra_fields:
+        fields.extend(extra_fields)
     class_fields = s.get_class_fields()
     return rx.box(
         h1_comp(text=title.title()),