Improve documentation for component lifecycle events and yield events (#1301)

* Improve documentation for component lifecycle events and yield events

Co-Authored-By: Alek Petuskey <[email protected]>

* Fix dictionary syntax in code examples to resolve flexdown parser error

Co-Authored-By: Alek Petuskey <[email protected]>

* Replace yield events section with on_load events documentation

Co-Authored-By: Alek Petuskey <[email protected]>

* Fix dictionary syntax in on_load example to resolve flexdown parser error

Co-Authored-By: Alek Petuskey <[email protected]>

* Add Event Reference header to distinguish between explanation and event listing

Co-Authored-By: Alek Petuskey <[email protected]>

* Fix broken link to page load events documentation and update GitHub stats

Co-Authored-By: Alek Petuskey <[email protected]>

* Revert changes to GitHub stats in constants.py

Co-Authored-By: Alek Petuskey <[email protected]>

* Update link format to use Reflex's template system

Co-Authored-By: Alek Petuskey <[email protected]>

* Fix page load events documentation link to use direct Markdown format

Co-Authored-By: Alek Petuskey <[email protected]>

* Add events import to fix template reference in documentation

Co-Authored-By: Alek Petuskey <[email protected]>

* Add detailed explanation of when lifecycle events are activated

Co-Authored-By: Alek Petuskey <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Alek Petuskey <[email protected]>
Co-authored-by: Alek Petuskey <[email protected]>

Author: devin-ai-integration[bot]

docs/api-reference/event_triggers.md

@@ -4,6 +4,7 @@ from datetime import datetime
 import reflex as rx
 
 from pcweb.templates.docpage import docdemo, h1_comp, text_comp, docpage
+from pcweb.pages.docs import events
 
 SYNTHETIC_EVENTS = [
     {
@@ -92,27 +93,70 @@ SYNTHETIC_EVENTS = [
     },
     {
         "name": "on_mount",
-        "description": "The on_mount event handler is called after the component is rendered on the page. It is similar to a page on_load event, although it does not necessarily fire when navigating between pages.",
+        "description": "The on_mount event handler is called after the component is rendered on the page. It is similar to a page on_load event, although it does not necessarily fire when navigating between pages. This event is particularly useful for initializing data, making API calls, or setting up component-specific state when a component first appears.",
         "state": """class MountState(rx.State):
     events: list[str] = []
+    data: list[dict] = []
+    loading: bool = False
 
     @rx.event
     def on_mount(self):
         self.events = self.events[-4:] + ["on_mount @ " + str(datetime.now())]
+        
+    @rx.event
+    async def load_data(self):
+        # Common pattern: Set loading state, yield to update UI, then fetch data
+        self.loading = True
+        yield
+        # Simulate API call
+        import asyncio
+        await asyncio.sleep(1)
+        self.data = [dict(id=1, name="Item 1"), dict(id=2, name="Item 2")]
+        self.loading = False
 """,
-        "example": """rx.vstack(rx.foreach(MountState.events, rx.text), on_mount=MountState.on_mount)""",
+        "example": """rx.vstack(
+    rx.heading("Component Lifecycle Demo"),
+    rx.foreach(MountState.events, rx.text),
+    rx.cond(
+        MountState.loading,
+        rx.spinner(),
+        rx.foreach(
+            MountState.data,
+            lambda item: rx.text(f"ID: {item['id']} - {item['name']}")
+        )
+    ),
+    on_mount=MountState.on_mount,
+)""",
     },
     {
         "name": "on_unmount",
-        "description": "The on_unmount event handler is called after removing the component from the page. However, on_unmount will only be called for internal navigation, not when following external links or refreshing the page.",
+        "description": "The on_unmount event handler is called after removing the component from the page. However, on_unmount will only be called for internal navigation, not when following external links or refreshing the page. This event is useful for cleaning up resources, saving state, or performing cleanup operations before a component is removed from the DOM.",
         "state": """class UnmountState(rx.State):
     events: list[str] = []
+    resource_id: str = "resource-12345"
+    status: str = "Resource active"
 
     @rx.event
     def on_unmount(self):
         self.events = self.events[-4:] + ["on_unmount @ " + str(datetime.now())]
+        # Common pattern: Clean up resources when component is removed
+        self.status = f"Resource {self.resource_id} cleaned up"
+        
+    @rx.event
+    def initialize_resource(self):
+        self.status = f"Resource {self.resource_id} initialized"
 """,
-        "example": """rx.vstack(rx.foreach(UnmountState.events, rx.text), on_unmount=UnmountState.on_unmount)""",
+        "example": """rx.vstack(
+    rx.heading("Unmount Demo"),
+    rx.foreach(UnmountState.events, rx.text),
+    rx.text(UnmountState.status),
+    rx.link(
+        rx.button("Navigate Away (Triggers Unmount)"),
+        href="/docs",
+    ),
+    on_mount=UnmountState.initialize_resource,
+    on_unmount=UnmountState.on_unmount,
+)""",
     },
     {
         "name": "on_mouse_up",
@@ -270,6 +314,70 @@ These events are triggered by event triggers.
 
 Event triggers are component specific and are listed in the documentation for each component.
 
+## Component Lifecycle Events
+
+Reflex components have lifecycle events like `on_mount` and `on_unmount` that allow you to execute code at specific points in a component's existence. These events are crucial for initializing data, cleaning up resources, and creating dynamic user interfaces.
+
+### When Lifecycle Events Are Activated
+
+- **on_mount**: This event is triggered immediately after a component is rendered and attached to the DOM. It fires:
+  - When a page containing the component is first loaded
+  - When a component is conditionally rendered (appears after being hidden)
+  - When navigating to a page containing the component using internal navigation
+  - It does NOT fire when the page is refreshed or when following external links
+
+- **on_unmount**: This event is triggered just before a component is removed from the DOM. It fires:
+  - When navigating away from a page containing the component using internal navigation
+  - When a component is conditionally removed from the DOM (e.g., via a condition that hides it)
+  - It does NOT fire when refreshing the page, closing the browser tab, or following external links
+
+## Page Load Events
+
+In addition to component lifecycle events, Reflex also provides page-level events like `on_load` that are triggered when a page loads. The `on_load` event is useful for:
+
+- Fetching data when a page first loads
+- Checking authentication status
+- Initializing page-specific state
+- Setting default values for cookies or browser storage
+
+You can specify an event handler to run when the page loads using the `on_load` parameter in the `@rx.page` decorator or `app.add_page()` method:
+
+```python
+class State(rx.State):
+    data: dict = dict()
+
+    @rx.event
+    def get_data(self):
+        # Fetch data when the page loads
+        self.data = fetch_data()
+
+@rx.page(on_load=State.get_data)
+def index():
+    return rx.text('Data loaded on page load')
+```
+
+This is particularly useful for authentication checks:
+
+```python
+class State(rx.State):
+    authenticated: bool = False
+
+    @rx.event
+    def check_auth(self):
+        # Check if user is authenticated
+        self.authenticated = check_auth()
+        if not self.authenticated:
+            return rx.redirect('/login')
+
+@rx.page(on_load=State.check_auth)
+def protected_page():
+    return rx.text('Protected content')
+```
+
+For more details on page load events, see the [page load events documentation]({events.page_load_events.path}).
+
+# Event Reference
+
 ```python eval
 rx.box(
     rx.divider(),