work on intro to state section

Author: rmorshea

Diff for: docs/source/_exts/widget_example.py

@@ -122,9 +122,12 @@ def _get_file_options(file: Path) -> list[str]:
     options = []
 
     for line in file.read_text().split("\n"):
-        file.name != "app.py" or print(repr(line))
-        if line.strip() and not OPTION_PATTERN.match(line):
+        if not line.strip():
+            continue
+        if not line.startswith("#"):
             break
+        if not OPTION_PATTERN.match(line):
+            continue
         option_string = line[1:].strip()
         if option_string:
             options.append(option_string)

Diff for: docs/source/adding-interactivity/components-with-state.rst

@@ -87,27 +87,145 @@ now let's just verify that this does in fact fix the problems from before:
 .. example:: adding_interactivity.adding_state_variable
     :activate-result:
 
-.. _Your first hook:
 
-.. dropdown:: :octicon:`light-bulb;2em` Your first hook
-    :color: warning
-    :open:
+Your First Hook
+---------------
 
-    In IDOM, ``use_state``, as well as any other function whose name starts with
-    ``use``, is called a "hook". These are special functions that should only be called
-    while IDOM is :ref:`rendering <the-rendering-process>`. They let you "hook into" the
-    different capabilities of IDOM's components of which ``use_state`` is just one (well
-    get into the other :ref:`later <managing state>`).
+In IDOM, ``use_state``, as well as any other function whose name starts with ``use``, is
+called a "hook". These are special functions that should only be called while IDOM is
+:ref:`rendering <the rendering process>`. They let you "hook into" the different
+capabilities of IDOM's components of which ``use_state`` is just one (well get into the
+other :ref:`later <managing state>`).
 
-    While hooks are just normal functions, but it's helpful to think of them as
-    :ref:`unconditioned <rules of hooks>` declarations about a component's needs. In
-    other words, you'll "use" hooks at the top of your component in the same way you
-    might "import" modules at the top of your Python files.
+While hooks are just normal functions, but it's helpful to think of them as
+:ref:`unconditioned <rules of hooks>` declarations about a component's needs. In other
+words, you'll "use" hooks at the top of your component in the same way you might
+"import" modules at the top of your Python files.
 
 
-Anatomy of ``use_state``
-------------------------
+Introduction to ``use_state``
+-----------------------------
 
+When you call :func:`~idom.core.hooks.use_state` inside the body of a component's render
+function, you're declaring that this component needs to remember something. That
+"something" which needs to be remembered, is known as **state**. So when we look at an
+assignment expression like the one below
+
+.. code-block::
+
+    index, set_index = use_state(0)
+
+we should read it as saying that ``index`` is a piece of state which must be
+remembered by the component that declared it. The argument to ``use_state`` (in this
+case ``0``) is then conveying what the initial value for ``index`` is.
+
+We should then understand that each time the component which owns this state renders
+``use_state`` will return a tuple containing two values - the current value of the state
+(``index``) and a function to change that value the next time the component is rendered.
+Thus, in this example:
+
+- ``index`` - is a **state variable** containing the currently stored value.
+- ``set_index`` - is a **state setter** for changing that value and triggering a re-render
+  of the component.
+
+.. note::
+
+    The convention is that, if you name your state variable ``thing``, your state setter
+    should be named ``set_thing``. While you could name them anything you want,
+    adhereing to the convention makes things easier to understand across projects.
+
+To understand how this works in context, let's break down our example:
+
+.. tab-set::
+
+    .. tab-item:: 1
+
+        .. raw:: html
+
+            <h2>Initial render</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 2
+
+    .. tab-item:: 2
+
+        .. raw:: html
+
+            <h2>Initial state declaration</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 3
+
+    .. tab-item:: 3
+
+        .. raw:: html
+
+            <h2>Define event handler</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 5
+
+    .. tab-item:: 4
+
+        .. raw:: html
+
+            <h2>Return the view</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 16
+
+    .. tab-item:: 5
+
+        .. raw:: html
+
+            <h2>User interaction</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+
+    .. tab-item:: 6
+
+        .. raw:: html
+
+            <h2>Event handler triggers</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 6
+
+    .. tab-item:: 7
+
+        .. raw:: html
+
+            <h2>Next render begins</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 2
+
+    .. tab-item:: 8
+
+        .. raw:: html
+
+            <h2>Next state is acquired</h2>
+
+        .. literalinclude:: /_examples/adding_interactivity/adding_state_variable/app.py
+            :lines: 12-33
+            :emphasize-lines: 3
+
+    .. tab-item:: 9
+
+        **Repeat...**
+
+        ...
+
+.. hint::
+
+    Try clicking through the numbered tabs to each highlighted step of execution
 
 Multiple State Declarations
 ---------------------------

Diff for: docs/source/adding-interactivity/responding-to-events.rst

@@ -1,8 +1,9 @@
 Responding to Events
 ====================
 
-IDOM lets you add event handlers to your parts of the interface. This means that you can
-assign functions that are triggered when a particular user interaction occurs like
+IDOM lets you add event handlers to your parts of the interface. These events handlers
+are functions which can be assigned to a part of a UI such that, when a user iteracts
+with the interface, those functions get triggered. Examples of interaction include
 clicking, hovering, of focusing on form inputs, and more.
 
 

Diff for: docs/source/creating-interfaces/your-first-components.rst

@@ -13,19 +13,19 @@ Defining a Component
 
 At their core, components are just normal Python functions that return HTML. To define a
 component you just need to add a ``@component`` `decorator
-<https://realpython.com/primer-on-python-decorators/>`__ to a function. Then, by
-convention, we name component functions like classes - with ``CamelCase``. So for
-example, if we wanted to write and then :ref:`display <Running IDOM>` a ``Photo``
-component we might write:
+<https://realpython.com/primer-on-python-decorators/>`__ to a function. Functions
+decorator in this way are known as **render function** and, by convention, we name them
+like classes - with ``CamelCase``. So for example, if we wanted to write, and then
+:ref:`display <Running IDOM>` a ``Photo`` component, we might write:
 
 .. example:: creating_interfaces.simple_photo
     :activate-result:
 
 .. warning::
 
-    If we had not decorated our ``Photo`` function with the ``@component`` decorator,
-    the server would start, but as soon as we tried to view the page it would be blank.
-    The servers logs would then indicate:
+    If we had not decorated our ``Photo``'s render function with the ``@component``
+    decorator, the server would start, but as soon as we tried to view the page it would
+    be blank. The servers logs would then indicate:
 
     .. code-block:: text
 

Diff for: docs/source/developing-idom/changelog.rst

@@ -347,11 +347,10 @@ update deletes the original button.
 0.25.0
 ------
 
-Completely refactors :ref:`Layout Dispatchers <Layout Dispatcher>` by switching from a
-class-based approach to one that leverages pure functions. While the logic itself isn't
-any simpler, it was easier to implement, and now hopefully understand, correctly. This
-conversion was motivated by several bugs that had cropped up related to improper usage
-of ``anyio``.
+Completely refactors layout dispatcher by switching from a class-based approach to one
+that leverages pure functions. While the logic itself isn't any simpler, it was easier
+to implement, and now hopefully understand, correctly. This conversion was motivated by
+several bugs that had cropped up related to improper usage of ``anyio``.
 
 **Issues Fixed:**
 

Diff for: docs/source/escape-hatches/javascript-components.rst

@@ -43,8 +43,8 @@ be using the ubiquitous React-based UI framework `Material UI`_.
 
 So now that we can display a Material UI Button we probably want to make it do
 something. Thankfully there's nothing new to learn here, you can pass event handlers to
-the button just as you did when :ref:`getting started <handling events>`. Thus, all we
-need to do is add an ``onClick`` handler to the component:
+the button just as you did when :ref:`getting started <responding to events>`. Thus, all
+we need to do is add an ``onClick`` handler to the component:
 
 .. example:: material_ui_button_on_click
 

Diff for: docs/source/getting-started/running-idom.rst

@@ -88,9 +88,9 @@ Presently IDOM's core library supports the following server implementations:
 - :mod:`idom.server.flask`
 - :mod:`idom.server.tornado`
 
-.. note::
+.. hint::
 
-    To install them, see the ref:`Installing Other Servers` section.
+    To install them, see the :ref:`Installing Other Servers` section.
 
 
 Available Server Types

Diff for: docs/source/index.rst

@@ -53,7 +53,7 @@ To get a rough idea of how to write apps in IDOM, take a look at the tiny `"hell
 .. example:: hello_world
     :activate-result:
 
-.. note::
+.. hint::
 
     Try clicking the **▶️ result** tab to see what this displays!