From 2a54b3465fab64d6a181a63d67b51565229ddb7c Mon Sep 17 00:00:00 2001
From: Ryan Morshead <ryan.morshead@gmail.com>
Date: Thu, 24 Feb 2022 22:26:22 -0800
Subject: [PATCH] reorganize creating-interfaces + add info on fragments (#685)

---
 .../index.rst}                                | 12 ++--
 docs/source/creating-interfaces/index.rst     | 22 +++----
 .../sorted_and_filtered_todo_list.py          |  0
 .../_examples/todo_from_list.py               |  0
 .../_examples/todo_list_with_keys.py          |  0
 .../index.rst}                                |  0
 .../_examples/bad_conditional_todo_list.py    |  0
 .../_examples/good_conditional_todo_list.py   |  0
 .../_examples/nested_photos.py                |  0
 .../_examples/parametrized_photos.py          |  2 +-
 .../_examples/simple_photo.py                 |  0
 .../_examples/todo_list.py                    |  0
 .../_examples/wrap_in_div.py                  | 13 +++++
 .../_examples/wrap_in_fragment.py             | 13 +++++
 .../index.rst}                                | 57 +++++++++++++++++++
 docs/source/index.rst                         |  2 +-
 tests/test_core/test_hooks.py                 |  2 +-
 17 files changed, 102 insertions(+), 21 deletions(-)
 rename docs/source/creating-interfaces/{html-with-idom.rst => html-with-idom/index.rst} (88%)
 rename docs/source/creating-interfaces/{ => rendering-data}/_examples/sorted_and_filtered_todo_list.py (100%)
 rename docs/source/creating-interfaces/{ => rendering-data}/_examples/todo_from_list.py (100%)
 rename docs/source/creating-interfaces/{ => rendering-data}/_examples/todo_list_with_keys.py (100%)
 rename docs/source/creating-interfaces/{rendering-data.rst => rendering-data/index.rst} (100%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/bad_conditional_todo_list.py (100%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/good_conditional_todo_list.py (100%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/nested_photos.py (100%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/parametrized_photos.py (86%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/simple_photo.py (100%)
 rename docs/source/creating-interfaces/{ => your-first-components}/_examples/todo_list.py (100%)
 create mode 100644 docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py
 create mode 100644 docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py
 rename docs/source/creating-interfaces/{your-first-components.rst => your-first-components/index.rst} (66%)

diff --git a/docs/source/creating-interfaces/html-with-idom.rst b/docs/source/creating-interfaces/html-with-idom/index.rst
similarity index 88%
rename from docs/source/creating-interfaces/html-with-idom.rst
rename to docs/source/creating-interfaces/html-with-idom/index.rst
index 79d2a6ed0..5bad18912 100644
--- a/docs/source/creating-interfaces/html-with-idom.rst
+++ b/docs/source/creating-interfaces/html-with-idom/index.rst
@@ -1,20 +1,19 @@
 HTML With IDOM
 ==============
 
-In a typical Python-base web application the resonsibility of defining the view along
+In a typical Python-base web application the responsibility of defining the view along
 with its backing data and logic are distributed between a client and server
 respectively. With IDOM, both these tasks are centralized in a single place. This is
 done by allowing HTML interfaces to be constructed in Python. Take a look at the two
-code examples below. The one on the left shows how to make a basic title and todo list
-using standard HTML, the one of the right uses IDOM in Python, and below is a view of
-what the HTML would look like if displayed:
+code examples below. The first one shows how to make a basic title and todo list using
+standard HTML, the second uses IDOM in Python, and below is a view of what the HTML
+would look like if displayed:
 
 .. grid:: 1 1 2 2
     :margin: 0
     :padding: 0
 
     .. grid-item::
-        :columns: 6
 
         .. code-block:: html
 
@@ -25,7 +24,6 @@ what the HTML would look like if displayed:
             </ul>
 
     .. grid-item::
-        :columns: 6
 
         .. testcode::
 
@@ -86,7 +84,7 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it
 
 In IDOM we add these attributes to elements using dictionaries. There are some notable
 differences though. The biggest being the fact that all names in IDOM use ``camelCase``
-instead of dash-sepearted words. For example, ``margin-left`` becomes ``marginLeft``.
+instead of dash-separated words. For example, ``margin-left`` becomes ``marginLeft``.
 Additionally, instead of specifying ``style`` using a string, we use a dictionary:
 
 .. testcode::
diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/creating-interfaces/index.rst
index 77f9fd4fc..74c662969 100644
--- a/docs/source/creating-interfaces/index.rst
+++ b/docs/source/creating-interfaces/index.rst
@@ -4,9 +4,9 @@ Creating Interfaces
 .. toctree::
     :hidden:
 
-    html-with-idom
-    your-first-components
-    rendering-data
+    html-with-idom/index
+    your-first-components/index
+    rendering-data/index
 
 .. dropdown:: :octicon:`bookmark-fill;2em` What You'll Learn
     :color: info
@@ -16,20 +16,20 @@ Creating Interfaces
     .. grid:: 1 2 2 2
 
         .. grid-item-card:: :octicon:`code-square` HTML with IDOM
-            :link: html-with-idom
+            :link: html-with-idom/index
             :link-type: doc
 
             Construct HTML layouts from the basic units of user interface functionality.
 
         .. grid-item-card:: :octicon:`package` Your First Components
-            :link: your-first-components
+            :link: your-first-components/index
             :link-type: doc
 
             Define reusable building blocks that it easier to construct complex
             interfaces.
 
         .. grid-item-card:: :octicon:`database` Rendering Data
-            :link: rendering-data
+            :link: rendering-data/index
             :link-type: doc
 
             Use data to organize and render HTML elements and components.
@@ -75,7 +75,7 @@ To recreate the same thing in IDOM you would write:
     )
 
 .. card::
-    :link: html-with-idom
+    :link: html-with-idom/index
     :link-type: doc
 
     :octicon:`book` Read More
@@ -94,10 +94,10 @@ create them we need to add an ``@component`` `decorator
 <https://realpython.com/primer-on-python-decorators/>`__. To see what this looks like in
 practice we'll quickly make a ``Photo`` component:
 
-.. idom:: _examples/simple_photo
+.. idom:: your-first-components/_examples/simple_photo
 
 .. card::
-    :link: your-first-components
+    :link: your-first-components/index
     :link-type: doc
 
     :octicon:`book` Read More
@@ -116,10 +116,10 @@ from data in this way must be orgnized with :ref:`"keys" <Organizing Items With
 One case where we might want to do this is if items in a todo list come from a list of
 data that we want to sort and filter:
 
-.. idom:: _examples/todo_list_with_keys
+.. idom:: rendering-data/_examples/todo_list_with_keys
 
 .. card::
-    :link: rendering-data
+    :link: rendering-data/index
     :link-type: doc
 
     :octicon:`book` Read More
diff --git a/docs/source/creating-interfaces/_examples/sorted_and_filtered_todo_list.py b/docs/source/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/sorted_and_filtered_todo_list.py
rename to docs/source/creating-interfaces/rendering-data/_examples/sorted_and_filtered_todo_list.py
diff --git a/docs/source/creating-interfaces/_examples/todo_from_list.py b/docs/source/creating-interfaces/rendering-data/_examples/todo_from_list.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/todo_from_list.py
rename to docs/source/creating-interfaces/rendering-data/_examples/todo_from_list.py
diff --git a/docs/source/creating-interfaces/_examples/todo_list_with_keys.py b/docs/source/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/todo_list_with_keys.py
rename to docs/source/creating-interfaces/rendering-data/_examples/todo_list_with_keys.py
diff --git a/docs/source/creating-interfaces/rendering-data.rst b/docs/source/creating-interfaces/rendering-data/index.rst
similarity index 100%
rename from docs/source/creating-interfaces/rendering-data.rst
rename to docs/source/creating-interfaces/rendering-data/index.rst
diff --git a/docs/source/creating-interfaces/_examples/bad_conditional_todo_list.py b/docs/source/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/bad_conditional_todo_list.py
rename to docs/source/creating-interfaces/your-first-components/_examples/bad_conditional_todo_list.py
diff --git a/docs/source/creating-interfaces/_examples/good_conditional_todo_list.py b/docs/source/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/good_conditional_todo_list.py
rename to docs/source/creating-interfaces/your-first-components/_examples/good_conditional_todo_list.py
diff --git a/docs/source/creating-interfaces/_examples/nested_photos.py b/docs/source/creating-interfaces/your-first-components/_examples/nested_photos.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/nested_photos.py
rename to docs/source/creating-interfaces/your-first-components/_examples/nested_photos.py
diff --git a/docs/source/creating-interfaces/_examples/parametrized_photos.py b/docs/source/creating-interfaces/your-first-components/_examples/parametrized_photos.py
similarity index 86%
rename from docs/source/creating-interfaces/_examples/parametrized_photos.py
rename to docs/source/creating-interfaces/your-first-components/_examples/parametrized_photos.py
index aeea41589..7eacb8f36 100644
--- a/docs/source/creating-interfaces/_examples/parametrized_photos.py
+++ b/docs/source/creating-interfaces/your-first-components/_examples/parametrized_photos.py
@@ -5,7 +5,7 @@
 def Photo(alt_text, image_id):
     return html.img(
         {
-            "src": f"https://picsum.photos/id/{image_id}/500/300",
+            "src": f"https://picsum.photos/id/{image_id}/500/200",
             "style": {"width": "50%"},
             "alt": alt_text,
         }
diff --git a/docs/source/creating-interfaces/_examples/simple_photo.py b/docs/source/creating-interfaces/your-first-components/_examples/simple_photo.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/simple_photo.py
rename to docs/source/creating-interfaces/your-first-components/_examples/simple_photo.py
diff --git a/docs/source/creating-interfaces/_examples/todo_list.py b/docs/source/creating-interfaces/your-first-components/_examples/todo_list.py
similarity index 100%
rename from docs/source/creating-interfaces/_examples/todo_list.py
rename to docs/source/creating-interfaces/your-first-components/_examples/todo_list.py
diff --git a/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py b/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py
new file mode 100644
index 000000000..2ddcd1060
--- /dev/null
+++ b/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_div.py
@@ -0,0 +1,13 @@
+from idom import component, html, run
+
+
+@component
+def MyTodoList():
+    return html.div(
+        html.h1("My Todo List"),
+        html.img({"src": "https://picsum.photos/id/0/500/300"}),
+        html.ul(html.li("The first thing I need to do is...")),
+    )
+
+
+run(MyTodoList)
diff --git a/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py b/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py
new file mode 100644
index 000000000..027e253bf
--- /dev/null
+++ b/docs/source/creating-interfaces/your-first-components/_examples/wrap_in_fragment.py
@@ -0,0 +1,13 @@
+from idom import component, html, run
+
+
+@component
+def MyTodoList():
+    return html._(
+        html.h1("My Todo List"),
+        html.img({"src": "https://picsum.photos/id/0/500/200"}),
+        html.ul(html.li("The first thing I need to do is...")),
+    )
+
+
+run(MyTodoList)
diff --git a/docs/source/creating-interfaces/your-first-components.rst b/docs/source/creating-interfaces/your-first-components/index.rst
similarity index 66%
rename from docs/source/creating-interfaces/your-first-components.rst
rename to docs/source/creating-interfaces/your-first-components/index.rst
index eeee7fa31..00b409ebb 100644
--- a/docs/source/creating-interfaces/your-first-components.rst
+++ b/docs/source/creating-interfaces/your-first-components/index.rst
@@ -42,6 +42,63 @@ component once and use it wherever and however you need to:
 .. idom:: _examples/nested_photos
 
 
+Return a Single Root Element
+----------------------------
+
+Components must return a "single root element". That one root element may have children,
+but you cannot for example, return a list of element from a component and expect it to
+be rendered correctly. If you want to return multiple elements you must wrap them in
+something like a :func:`html.div <idom.html.div>`:
+
+.. idom:: _examples/wrap_in_div
+
+If don't want to add an extra ``div`` you can use a "fragment" instead with the
+:func:`html._ <idom.html._>` function:
+
+.. idom:: _examples/wrap_in_fragment
+
+Fragments allow you to group elements together without leaving any trace in the UI. For
+example, the first code sample written with IDOM will produce the second HTML code
+block:
+
+.. grid:: 1 2 2 2
+    :margin: 0
+    :padding: 0
+
+    .. grid-item::
+
+        .. testcode::
+
+            from idom import html
+
+            html.ul(
+                html._(
+                    html.li("Group 1 Item 1"),
+                    html.li("Group 1 Item 2"),
+                    html.li("Group 1 Item 3"),
+                ),
+                html._(
+                    html.li("Group 2 Item 1"),
+                    html.li("Group 2 Item 2"),
+                    html.li("Group 2 Item 3"),
+                )
+            )
+
+    .. grid-item::
+
+        .. code-block:: html
+
+            <ul>
+              <li>Group 1 Item 1</li>
+              <li>Group 1 Item 2</li>
+              <li>Group 1 Item 3</li>
+              <li>Group 2 Item 1</li>
+              <li>Group 2 Item 2</li>
+              <li>Group 2 Item 3</li>
+            </ul>
+
+
+
 Parametrizing Components
 ------------------------
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e7ecbc18d..516a33a25 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -123,7 +123,7 @@ combine these elements into reusable :ref:`"components" <your first components>`
 sections that follow you'll learn how these UI elements are created and organized into
 components. Then, you'll use this knowledge to create interfaces from raw data:
 
-.. idom:: creating-interfaces/_examples/todo_list_with_keys
+.. idom:: creating-interfaces/rendering-data/_examples/todo_list_with_keys
 
 .. card::
     :link: creating-interfaces/index
diff --git a/tests/test_core/test_hooks.py b/tests/test_core/test_hooks.py
index d3793a59e..a95724856 100644
--- a/tests/test_core/test_hooks.py
+++ b/tests/test_core/test_hooks.py
@@ -1161,5 +1161,5 @@ def SetStateDuringRender():
         assert render_count.current == 2
 
         # there should be no more renders to perform
-        with pytest.raises(asyncio.exceptions.TimeoutError):
+        with pytest.raises(asyncio.TimeoutError):
             await asyncio.wait_for(layout.render(), timeout=0.1)