Refactoring related to new docs

Author: Archmonger

src/reactpy_django/components.py

@@ -30,7 +30,7 @@
     from django.forms import Form, ModelForm
     from django.views import View
 
-    from reactpy_django.types import FormEvent
+    from reactpy_django.types import AsyncFormEvent, SyncFormEvent
 
 
 def view_to_component(
@@ -121,23 +121,45 @@ def django_js(static_path: str, key: Key | None = None):
 def django_form(
     form: type[Form | ModelForm],
     *,
-    on_success: Callable[[FormEvent], None] | None = None,
-    on_error: Callable[[FormEvent], None] | None = None,
-    on_submit: Callable[[FormEvent], None] | None = None,
-    on_change: Callable[[FormEvent], None] | None = None,
+    on_success: AsyncFormEvent | SyncFormEvent | None = None,
+    on_error: AsyncFormEvent | SyncFormEvent | None = None,
+    on_receive_data: AsyncFormEvent | SyncFormEvent | None = None,
+    on_change: AsyncFormEvent | SyncFormEvent | None = None,
     auto_save: bool = True,
     extra_props: dict[str, Any] | None = None,
     extra_transforms: Sequence[Callable[[VdomDict], Any]] | None = None,
     form_template: str | None = None,
-    top_children: Sequence = (),
-    bottom_children: Sequence = (),
+    top_children: Sequence[Any] = (),
+    bottom_children: Sequence[Any] = (),
     key: Key | None = None,
 ):
+    """Converts a Django form to a ReactPy component.
+
+    Args:
+        form: The form instance to convert.
+
+    Keyword Args:
+        on_success: A callback function that is called when the form is successfully submitted.
+        on_error: A callback function that is called when the form submission fails.
+        on_receive_data: A callback function that is called before newly submitted form data is rendered.
+        on_change: A callback function that is called when the form is changed.
+        auto_save: If `True`, the form will automatically call `save` on successful submission of \
+            a `ModelForm`. This has no effect on regular `Form` instances.
+        extra_props: Additional properties to add to the `html.form` element.
+        extra_transforms: A list of functions that transforms the newly generated VDOM. \
+            The functions will be repeatedly called on each VDOM node.
+        form_template: The template to use for the form. If `None`, Django's default template is used.
+        top_children: Additional elements to add to the top of the form.
+        bottom_children: Additional elements to add to the bottom of the form.
+        key: A key to uniquely identify this component which is unique amongst a component's \
+            immediate siblings.
+    """
+
     return _django_form(
         form=form,
         on_success=on_success,
         on_error=on_error,
-        on_submit=on_submit,
+        on_receive_data=on_receive_data,
         on_change=on_change,
         auto_save=auto_save,
         extra_props=extra_props or {},

src/reactpy_django/forms/components.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Union, cast
 from uuid import uuid4
@@ -18,7 +19,7 @@
     transform_value_prop_on_input_element,
 )
 from reactpy_django.forms.utils import convert_boolean_fields, convert_multiple_choice_fields
-from reactpy_django.types import FormEvent
+from reactpy_django.types import AsyncFormEvent, FormEventData, SyncFormEvent
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -31,13 +32,14 @@
 )
 
 
+# TODO: Create types for AsyncFormEvent and FormEvent
 @component
 def _django_form(
     form: type[Form | ModelForm],
-    on_success: Callable[[FormEvent], None] | None,
-    on_error: Callable[[FormEvent], None] | None,
-    on_submit: Callable[[FormEvent], None] | None,
-    on_change: Callable[[FormEvent], None] | None,
+    on_success: AsyncFormEvent | SyncFormEvent | None,
+    on_error: AsyncFormEvent | SyncFormEvent | None,
+    on_receive_data: AsyncFormEvent | SyncFormEvent | None,
+    on_change: AsyncFormEvent | SyncFormEvent | None,
     auto_save: bool,
     extra_props: dict,
     extra_transforms: Sequence[Callable[[VdomDict], Any]],
@@ -64,13 +66,12 @@ def _django_form(
             "Do NOT initialize your form by calling it (ex. `MyForm()`)."
         )
         raise TypeError(msg)
-    if "id" in extra_props:
-        msg = "The `extra_props` argument cannot contain an `id` key."
-        raise ValueError(msg)
 
     # Try to initialize the form with the provided data
     initialized_form = form(data=submitted_data)
-    form_event = FormEvent(form=initialized_form, data=submitted_data or {}, set_data=set_submitted_data)
+    form_event = FormEventData(
+        form=initialized_form, submitted_data=submitted_data or {}, set_submitted_data=set_submitted_data
+    )
 
     # Validate and render the form
     @hooks.use_effect
@@ -80,9 +81,15 @@ async def render_form():
             await database_sync_to_async(initialized_form.full_clean)()
             success = not initialized_form.errors.as_data()
             if success and on_success:
-                on_success(form_event)
+                if asyncio.iscoroutinefunction(on_success):
+                    await on_success(form_event)
+                else:
+                    on_success(form_event)
             if not success and on_error:
-                on_error(form_event)
+                if asyncio.iscoroutinefunction(on_error):
+                    await on_error(form_event)
+                else:
+                    on_error(form_event)
             if success and auto_save and isinstance(initialized_form, ModelForm):
                 await database_sync_to_async(initialized_form.save)()
                 set_submitted_data(None)
@@ -93,28 +100,43 @@ async def render_form():
         if new_form != rendered_form:
             set_rendered_form(new_form)
 
-    def on_submit_callback(new_data: dict[str, Any]):
+    async def on_submit_callback(new_data: dict[str, Any]):
         """Callback function provided directly to the client side listener. This is responsible for transmitting
         the submitted form data to the server for processing."""
         convert_multiple_choice_fields(new_data, initialized_form)
         convert_boolean_fields(new_data, initialized_form)
 
-        if on_submit:
-            on_submit(FormEvent(form=initialized_form, data=new_data, set_data=set_submitted_data))
+        if on_receive_data:
+            new_form_event = FormEventData(
+                form=initialized_form, submitted_data=new_data, set_submitted_data=set_submitted_data
+            )
+            if asyncio.iscoroutinefunction(on_receive_data):
+                await on_receive_data(new_form_event)
+            else:
+                on_receive_data(new_form_event)
 
         if submitted_data != new_data:
             set_submitted_data(new_data)
 
+    async def _on_change(_event):
+        """Event that exist solely to allow the user to detect form changes."""
+        if on_change:
+            if asyncio.iscoroutinefunction(on_change):
+                await on_change(form_event)
+            else:
+                on_change(form_event)
+
     if not rendered_form:
         return None
 
     return html.form(
-        {
+        extra_props
+        | {
             "id": f"reactpy-{uuid}",
+            # Intercept the form submission to prevent the browser from navigating
             "onSubmit": event(lambda _: None, prevent_default=True),
-            "onChange": on_change(form_event) if on_change else lambda _: None,
-        }
-        | extra_props,
+            "onChange": _on_change,
+        },
         DjangoForm({"onSubmitCallback": on_submit_callback, "formId": f"reactpy-{uuid}"}),
         *top_children,
         utils.html_to_vdom(

src/reactpy_django/types.py

@@ -54,12 +54,20 @@ def __call__(self, *args: FuncParams.args, **kwargs: FuncParams.kwargs) -> None:
 
 
 @dataclass
-class FormEvent:
+class FormEventData:
     """State of a form provided to Form custom events."""
 
     form: Form | ModelForm
-    data: dict[str, Any]
-    set_data: Callable[[dict[str, Any] | None], None]
+    submitted_data: dict[str, Any]
+    set_submitted_data: Callable[[dict[str, Any] | None], None]
+
+
+class AsyncFormEvent(Protocol):
+    async def __call__(self, event: FormEventData) -> None: ...
+
+
+class SyncFormEvent(Protocol):
+    def __call__(self, event: FormEventData) -> None: ...
 
 
 class AsyncPostprocessor(Protocol):