misc progress on your first component section

rmorshea · rmorshea · commit dece554d166f · 2021-11-11T02:05:20.000-08:00
diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/creating-interfaces/index.rst
@@ -5,7 +5,7 @@ Creating Interfaces
     :hidden:
 
     html-with-idom
-    your-first-component
+    your-first-components
     parametrizing-components
     conditional-rendering
     dynamic-element-children
@@ -23,11 +23,11 @@ Creating Interfaces
             Learn how to construct HTML layouts with IDOM and the underlying data
             structure we use to represent them.
 
-        .. grid-item-card:: :octicon:`package` Your First Component
-            :link: your-first-component
+        .. grid-item-card:: :octicon:`package` Your First Components
+            :link: your-first-components
             :link-type: doc
 
-            Discover what components are and why their one of IDOM's foundational
+            Discover what components are and why they're one of IDOM's foundational
             concepts.
 
         .. grid-item-card:: :octicon:`plug` Parametrizing Components
@@ -63,9 +63,9 @@ Section 1: HTML with IDOM
 
 In a typical Python-base web application the resonsibility 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. Let's consider the HTML
-sample below:
+respectively. With IDOM, both these tasks are centralized in a single place. The most
+foundational pilar of this capability is formed by allowing HTML interfaces to be
+constructed in Python. Let's consider the HTML sample below:
 
 .. code-block:: html
 
@@ -102,8 +102,34 @@ To recreate the same thing in IDOM you would write:
     use to represent them.
 
 
-Section 2: Your First Component
--------------------------------
+Section 2: Your First Components
+--------------------------------
+
+The next building block in our journey with IDOM are components. At their core,
+components are just a normal Python functions that return :ref:`HTML <HTML with IDOM>`.
+The one special thing about them that we need to be concerned with now, is that to
+create them they require the addition of the :func:`~idom.core.component.component`
+decorator. Take a quick look at this "hello world" example you make have seen earlier to
+check out what this looks like in practice:
+
+.. example:: hello_world
+    :activate-result:
+
+.. note::
+
+    Not all functions that return HTML need to be decorated with the ``@component``
+    decorator - when and where they are required will be discussed when we start
+    :ref:`adding interactivity`.
+
+.. card::
+    :link: html-with-idom
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Discover what components are and why they're one of IDOM's foundational concepts.
+
 
 
 Section 3: Parametrizing Components
diff --git a/docs/source/creating-interfaces/your-first-component.rst b/docs/source/creating-interfaces/your-first-component.rst
diff --git a/docs/source/creating-interfaces/your-first-components.rst b/docs/source/creating-interfaces/your-first-components.rst
@@ -0,0 +1,76 @@
+Your First Component
+====================
+
+The next building block in our journey with IDOM are components. At their core,
+components are just a normal Python functions that return :ref:`HTML <HTML with IDOM>`.
+The one special thing about them that we need to be concerned with now, is that to
+create them they require the addition of the :func:`~idom.core.component.component`
+decorator. Take a quick look at this "hello world" example you make have seen earlier to
+check out what this looks like in practice:
+
+.. example:: hello_world
+    :activate-result:
+
+.. note::
+
+    Not all functions that return HTML need to be decorated with the ``@component``
+    decorator - when and where they are required will be discussed when we start
+    :ref:`adding interactivity`.
+
+In the code above we have a function ``App`` that is decorated with ``@component`` to
+turn it into a component. This function then gets passed to
+:func:`~idom.server.prefab.run` in order to :ref:`run a server <Running IDOM>` to
+display it. If we had not decorated our ``App`` 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
+
+    TypeError: Expected a ComponentType, not dict.
+
+To see why this is we can check out what happens when we call ``App`` with and without
+the ``@component`` decorator. In the first instance we get a dictionary representing our
+HTML:
+
+.. testcode::
+
+    from idom import html
+
+    def App():
+        return html.h1("Hello, world!")
+
+    print(App())
+
+.. testoutput::
+
+    {'tagName': 'h1', 'children': ['Hello, world!']}
+
+But, if we decorate it we instead find:
+
+.. testcode::
+
+    from idom import component, html, ComponentType
+
+    @component
+    def App():
+        return html.h1("Hello, world!")
+
+    app = App()
+    print(app)
+    print(type(app))
+
+.. testcode::
+    :hide:
+
+    import re
+    # update the output code block below and this regex pattern if this fails
+    assert re.match("Component\(\d+\)", str(App()))
+
+.. code-block::
+
+    App(7fc0d881fbd0)
+    <class 'idom.core.component.Component'>
+
+This explains the error. If we don't decorate the function we just get out out HTML
+dict, but if we do, we get this special ``Component`` object back. Since the ``run``
+function expects the latter to do its job we get an error about it.
diff --git a/src/idom/__init__.py b/src/idom/__init__.py
@@ -4,6 +4,7 @@
 from .core.dispatcher import Stop
 from .core.events import EventHandler, event
 from .core.layout import Layout
+from .core.proto import ComponentType, VdomDict
 from .core.vdom import vdom
 from .sample import run_sample_app
 from .server.prefab import run
@@ -17,6 +18,7 @@
 __all__ = [
     "component",
     "Component",
+    "ComponentType",
     "config",
     "event",
     "EventHandler",
@@ -28,9 +30,10 @@
     "log",
     "multiview",
     "Ref",
-    "run",
     "run_sample_app",
+    "run",
     "Stop",
     "vdom",
+    "VdomDict",
     "web",
 ]
diff --git a/src/idom/core/component.py b/src/idom/core/component.py
@@ -74,6 +74,6 @@ def __repr__(self) -> str:
         else:
             items = ", ".join(f"{k}={v!r}" for k, v in args.items())
             if items:
-                return f"{self._func.__name__}({id(self)}, {items})"
+                return f"{self._func.__name__}({id(self):02x}, {items})"
             else:
-                return f"{self._func.__name__}({id(self)})"
+                return f"{self._func.__name__}({id(self):02x})"
diff --git a/src/idom/core/layout.py b/src/idom/core/layout.py
@@ -83,7 +83,7 @@ class Layout:
     def __init__(self, root: "ComponentType") -> None:
         super().__init__()
         if not isinstance(root, ComponentType):
-            raise TypeError("Expected an ComponentType, not %r" % root)
+            raise TypeError(f"Expected a ComponentType, not {type(root)!r}.")
         self.root = root
 
     def __enter__(self: _Self) -> _Self:
diff --git a/tests/test_core/test_component.py b/tests/test_core/test_component.py
@@ -8,7 +8,7 @@ def MyComponent(a, *b, **c):
 
     mc1 = MyComponent(1, 2, 3, x=4, y=5)
 
-    expected = f"MyComponent({id(mc1)}, a=1, b=(2, 3), c={{'x': 4, 'y': 5}})"
+    expected = f"MyComponent({id(mc1):02x}, a=1, b=(2, 3), c={{'x': 4, 'y': 5}})"
     assert repr(mc1) == expected
 
     # not enough args supplied to function
diff --git a/tests/test_core/test_layout.py b/tests/test_core/test_layout.py
@@ -20,7 +20,7 @@ def MyComponent():
 
     my_component = MyComponent()
     layout = idom.Layout(my_component)
-    assert str(layout) == f"Layout(MyComponent({id(my_component)}))"
+    assert str(layout) == f"Layout(MyComponent({id(my_component):02x}))"
 
 
 def test_layout_expects_abstract_component():
