re-organize widgets directory

Author: rmorshea

docs/main.py

@@ -6,9 +6,9 @@
 from sanic import Sanic, response
 
 import idom
-from idom.client.manage import web_modules_dir
+from idom.config import IDOM_WED_MODULES_DIR
 from idom.server.sanic import PerClientStateServer
-from idom.widgets.utils import multiview
+from idom.widgets import multiview
 
 
 HERE = Path(__file__).parent
@@ -18,7 +18,7 @@
 def make_app():
     app = Sanic(__name__)
     app.static("/docs", str(HERE / "build"))
-    app.static("/_modules", str(web_modules_dir()))
+    app.static("/_modules", str(IDOM_WED_MODULES_DIR.current))
 
     @app.route("/")
     async def forward_to_index(request):

docs/source/auto/api-reference.rst

@@ -55,10 +55,10 @@ API Reference
 .. automodule:: idom.utils
     :members:
 
-.. automodule:: idom.widgets.html
+.. automodule:: idom.html
     :members:
 
-.. automodule:: idom.widgets.utils
+.. automodule:: idom.widgets
     :members:
 
 Misc Modules

docs/source/examples.rst

@@ -59,7 +59,7 @@ Simply install your javascript library of choice using the ``idom`` CLI:
 
     idom install victory
 
-Then import the module with :class:`~idom.widgets.utils.Module`:
+Then import the module with :mod:`~idom.web.module`:
 
 .. example:: victory_chart
 

scripts/one_example.py

@@ -5,7 +5,7 @@
 from threading import Thread
 
 import idom
-from idom.widgets.utils import hotswap
+from idom.widgets import hotswap
 
 
 here = Path(__file__).parent

src/idom/__init__.py

@@ -10,16 +10,15 @@
 
 __author__ = "idom-team"
 
-from . import config, log, web
+from . import config, html, log, web
 from .core import hooks
 from .core.component import Component, component
 from .core.events import Events, event
 from .core.layout import Layout
 from .core.vdom import VdomDict, vdom
 from .server.prefab import run
 from .utils import Ref, html_to_vdom
-from .widgets.html import html
-from .widgets.utils import hotswap, multiview
+from .widgets import hotswap, multiview
 
 
 __all__ = [

src/idom/core/vdom.py

@@ -106,7 +106,7 @@ class _VdomDictRequired(TypedDict, total=True):
 
 
 class VdomDict(_VdomDictRequired, _VdomDictOptional):
-    """A VDOM dictionary"""
+    """A VDOM dictionary - see :ref:`VDOM Mimetype` for more info"""
 
 
 _AttributesAndChildrenArg = Union[Mapping[str, Any], str, Iterable[Any], Any]
@@ -201,7 +201,7 @@ def constructor(
     qualname_prefix = constructor.__qualname__.rsplit(".", 1)[0]
     constructor.__qualname__ = qualname_prefix + f".{tag}"
     constructor.__doc__ = (
-        f"""Create a new ``<{tag}/>`` - returns :ref:`VDOM <VDOM Mimetype>`."""
+        f"""Create a new ``<{tag}/>`` - returns a :class:`VdomDict`."""
     )
 
     return constructor

src/idom/html.py

@@ -0,0 +1,218 @@
+"""
+Standard HTML Elements
+======================
+
+
+External sources
+----------------
+
+link = make_vdom_constructor("link", allow_children=False)
+
+
+Content Sectioning
+------------------
+
+- :func:`style`
+- :func:`address`
+- :func:`article`
+- :func:`aside`
+- :func:`footer`
+- :func:`h1`
+- :func:`h2`
+- :func:`h3`
+- :func:`h4`
+- :func:`h5`
+- :func:`h6`
+- :func:`header`
+- :func:`hgroup`
+- :func:`nav`
+- :func:`section`
+
+
+Text Content
+------------
+- :func:`blockquote`
+- :func:`dd`
+- :func:`div`
+- :func:`dl`
+- :func:`dt`
+- :func:`figcaption`
+- :func:`figure`
+- :func:`hr`
+- :func:`li`
+- :func:`ol`
+- :func:`p`
+- :func:`pre`
+- :func:`ul`
+
+
+Inline Text Semantics
+---------------------
+
+- :func:`a`
+- :func:`abbr`
+- :func:`b`
+- :func:`br`
+- :func:`cite`
+- :func:`code`
+- :func:`data`
+- :func:`em`
+- :func:`i`
+- :func:`kbd`
+- :func:`mark`
+- :func:`q`
+- :func:`s`
+- :func:`samp`
+- :func:`small`
+- :func:`span`
+- :func:`strong`
+- :func:`sub`
+- :func:`sup`
+- :func:`time`
+- :func:`u`
+- :func:`var`
+
+
+Image and video
+---------------
+
+- :func:`img`
+- :func:`audio`
+- :func:`video`
+- :func:`source`
+
+
+Table Content
+-------------
+
+- :func:`caption`
+- :func:`col`
+- :func:`colgroup`
+- :func:`table`
+- :func:`tbody`
+- :func:`td`
+- :func:`tfoot`
+- :func:`th`
+- :func:`thead`
+- :func:`tr`
+
+
+Forms
+-----
+
+- :func:`meter`
+- :func:`output`
+- :func:`progress`
+- :func:`input`
+- :func:`button`
+- :func:`label`
+- :func:`fieldset`
+- :func:`legend`
+
+
+Interactive Elements
+--------------------
+
+- :func:`details`
+- :func:`dialog`
+- :func:`menu`
+- :func:`menuitem`
+- :func:`summary`
+"""
+
+from .core.vdom import make_vdom_constructor
+
+
+# External sources
+link = make_vdom_constructor("link", allow_children=False)
+
+# Content sectioning
+style = make_vdom_constructor("style")
+address = make_vdom_constructor("address")
+article = make_vdom_constructor("article")
+aside = make_vdom_constructor("aside")
+footer = make_vdom_constructor("footer")
+h1 = make_vdom_constructor("h1")
+h2 = make_vdom_constructor("h2")
+h3 = make_vdom_constructor("h3")
+h4 = make_vdom_constructor("h4")
+h5 = make_vdom_constructor("h5")
+h6 = make_vdom_constructor("h6")
+header = make_vdom_constructor("header")
+hgroup = make_vdom_constructor("hgroup")
+nav = make_vdom_constructor("nav")
+section = make_vdom_constructor("section")
+
+# Text content
+blockquote = make_vdom_constructor("blockquote")
+dd = make_vdom_constructor("dd")
+div = make_vdom_constructor("div")
+dl = make_vdom_constructor("dl")
+dt = make_vdom_constructor("dt")
+figcaption = make_vdom_constructor("figcaption")
+figure = make_vdom_constructor("figure")
+hr = make_vdom_constructor("hr", allow_children=False)
+li = make_vdom_constructor("li")
+ol = make_vdom_constructor("ol")
+p = make_vdom_constructor("p")
+pre = make_vdom_constructor("pre")
+ul = make_vdom_constructor("ul")
+
+# Inline text semantics
+a = make_vdom_constructor("a")
+abbr = make_vdom_constructor("abbr")
+b = make_vdom_constructor("b")
+br = make_vdom_constructor("br", allow_children=False)
+cite = make_vdom_constructor("cite")
+code = make_vdom_constructor("code")
+data = make_vdom_constructor("data")
+em = make_vdom_constructor("em")
+i = make_vdom_constructor("i")
+kbd = make_vdom_constructor("kbd")
+mark = make_vdom_constructor("mark")
+q = make_vdom_constructor("q")
+s = make_vdom_constructor("s")
+samp = make_vdom_constructor("samp")
+small = make_vdom_constructor("small")
+span = make_vdom_constructor("span")
+strong = make_vdom_constructor("strong")
+sub = make_vdom_constructor("sub")
+sup = make_vdom_constructor("sup")
+time = make_vdom_constructor("time")
+u = make_vdom_constructor("u")
+var = make_vdom_constructor("var")
+
+# Image and video
+img = make_vdom_constructor("img", allow_children=False)
+audio = make_vdom_constructor("audio")
+video = make_vdom_constructor("video")
+source = make_vdom_constructor("source", allow_children=False)
+
+# Table content
+caption = make_vdom_constructor("caption")
+col = make_vdom_constructor("col")
+colgroup = make_vdom_constructor("colgroup")
+table = make_vdom_constructor("table")
+tbody = make_vdom_constructor("tbody")
+td = make_vdom_constructor("td")
+tfoot = make_vdom_constructor("tfoot")
+th = make_vdom_constructor("th")
+thead = make_vdom_constructor("thead")
+tr = make_vdom_constructor("tr")
+
+# Forms
+meter = make_vdom_constructor("meter")
+output = make_vdom_constructor("output")
+progress = make_vdom_constructor("progress")
+input = make_vdom_constructor("input", allow_children=False)
+button = make_vdom_constructor("button")
+label = make_vdom_constructor("label")
+fieldset = make_vdom_constructor("fieldset")
+legend = make_vdom_constructor("legend")
+
+# Interactive elements
+details = make_vdom_constructor("details")
+dialog = make_vdom_constructor("dialog")
+menu = make_vdom_constructor("menu")
+menuitem = make_vdom_constructor("menuitem")
+summary = make_vdom_constructor("summary")

src/idom/server/prefab.py

@@ -7,7 +7,7 @@
 from typing import Any, Dict, Optional, Tuple, TypeVar
 
 from idom.core.component import ComponentConstructor
-from idom.widgets.utils import MountFunc, MultiViewMount, hotswap, multiview
+from idom.widgets import MountFunc, MultiViewMount, hotswap, multiview
 
 from .proto import Server, ServerFactory
 from .utils import find_available_port, find_builtin_server_type

src/idom/web/module.py

@@ -1,3 +1,8 @@
+"""
+Web Modules
+===========
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass

src/idom/widgets/utils.py renamed to src/idom/widgets.py

@@ -4,11 +4,65 @@
 """
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, Optional, Set, Tuple, TypeVar
+from base64 import b64encode
+from typing import Any, Callable, Dict, Optional, Set, Tuple, TypeVar, Union
 
-from idom.core import hooks
-from idom.core.component import ComponentConstructor, component
-from idom.utils import Ref
+import idom
+
+from . import html
+from .core import hooks
+from .core.component import ComponentConstructor, component
+from .core.vdom import VdomDict
+from .utils import Ref
+
+
+def image(
+    format: str,
+    value: Union[str, bytes] = "",
+    attributes: Optional[Dict[str, Any]] = None,
+) -> VdomDict:
+    """Utility for constructing an image from a string or bytes
+
+    The source value will automatically be encoded to base64
+    """
+    if format == "svg":
+        format = "svg+xml"
+
+    if isinstance(value, str):
+        bytes_value = value.encode()
+    else:
+        bytes_value = value
+
+    base64_value = b64encode(bytes_value).decode()
+    src = f"data:image/{format};base64,{base64_value}"
+
+    return {"tagName": "img", "attributes": {"src": src, **(attributes or {})}}
+
+
+@component
+def Input(
+    callback: Callable[[str], None],
+    type: str,
+    value: str = "",
+    attributes: Optional[Dict[str, Any]] = None,
+    cast: Optional[Callable[[str], Any]] = None,
+    ignore_empty: bool = True,
+) -> VdomDict:
+    """Utility for making an ``<input/>`` with a callback"""
+    attrs = attributes or {}
+    value, set_value = idom.hooks.use_state(value)
+
+    events = idom.Events()
+
+    @events.on("change")
+    def on_change(event: Dict[str, Any]) -> None:
+        value = event["value"]
+        set_value(value)
+        if not value and ignore_empty:
+            return
+        callback(value if cast is None else cast(value))
+
+    return html.input({"type": type, "value": value, **attrs}, event_handlers=events)
 
 
 MountFunc = Callable[[ComponentConstructor], None]