Possible custom hooks example 647

docs/source/about/changelog.rst

@@ -23,7 +23,8 @@ more info, see the :ref:`Contributor Guide <Creating a Changelog Entry>`.
 Unreleased
 ----------
 
-No changes.
+**Added**
+- :issue:`647` - Added an exmaple for how to build a custom hook that returns functions
 
 
 v1.0.0

docs/source/guides/adding-interactivity/components-with-state/_examples/custom_hook/main.py

@@ -0,0 +1,25 @@
+from reactpy import component, html, run
+
+# Import custom hook from use_counting_hook.py file
+from use_counting_hook import use_counting_hook
+
+# Defining a component using the reactpy's component decorator
+@component
+def Example_Component():
+
+    # Using the custom hook to initialize count, increment, decrement, and reset functions. import them in the same order as they are returned in the hook file
+    count, increment, decrement, reset = use_counting_hook(0)
+
+    # The component renders a div which contains three buttons and the current count
+    return html.div(
+        # Button to reset count, calling reset function on click
+        html.button({"on_click": lambda event: reset()}, "Reset"),
+        # Button to increment count, calling increment function on click
+        html.button({"on_click": lambda event: increment()}, "add"),
+        # Button to decrement count, calling decrement function on click
+        html.button({"on_click": lambda event: decrement()}, "subtract"),
+        # Displaying current count
+        f"Count: {count}"
+    )
+
+run(Example_Component)

docs/source/guides/adding-interactivity/components-with-state/_examples/custom_hook/use_counting_hook.py

@@ -0,0 +1,39 @@
+from reactpy import hooks
+
+# This is a custom hook that provides a counter functionality.
+def use_counting_hook(initial_value=0):
+
+    # The reducer function defines how the state (count) should be updated based on the action that is dispatched.
+    def reducer(count, action):
+        if action == "increment":
+            # When the "increment" action is dispatched, the count is incremented.
+            return count + 1
+        elif action == "decrement":
+            # When the "decrement" action is dispatched, the count is decremented.
+            return count - 1
+        elif action == "reset":
+            # When the "reset" action is dispatched, the count is reset to the initial value.
+            return initial_value
+        else:
+            # If an unknown action is dispatched, raise an error.
+            msg = f"Unknown action '{action}'"
+            raise ValueError(msg)
+
+    # Use the use_reducer hook from reactpy. This hook provides the current state (count) and a dispatch function that can be used to update the state.
+    count, dispatch = hooks.use_reducer(reducer, initial_value)
+
+    # Define a function to increment the count by dispatching the "increment" action.
+    def increment():
+        dispatch("increment")
+
+    # Define a function to decrement the count by dispatching the "decrement" action.
+    def decrement():
+        dispatch("decrement")
+
+    # Define a function to reset the count by dispatching the "reset" action.
+    def reset():
+        dispatch("reset")
+
+    # Return the current count along with the increment, decrement, and reset functions.
+    # These can be used in a component to display and update the count.
+    return count, increment, decrement, reset