@pyscript/core 0.7.10 → 0.7.12

package/src/stdlib/pyscript/web.py

@@ -1,184 +1,585 @@
-"""Lightweight interface to the DOM and HTML elements."""
+"""
+A lightweight Pythonic interface to the DOM and HTML elements that helps you
+interact with web pages, making it easy to find, create, manipulate, and
+compose HTML elements from Python.
+
+Highlights include:
 
-# `when` is not used in this module. It is imported here save the user an additional
-# import (i.e. they can get what they need from `pyscript.web`).
+Use the `page` object to find elements on the current page:
+
+```python
+from pyscript import web
 
-# from __future__ import annotations  # CAUTION: This is not supported in MicroPython.
+
+# Find by CSS selector (returns an ElementCollection).
+divs = web.page.find("div")
+buttons = web.page.find(".button-class")
+
+# Get element by ID (returns single Element or None).
+header = web.page["header-id"]
+header = web.page["#header-id"]  # the "#" prefix is optional.
+
+# Access page structure.
+web.page.body.append(some_element)
+web.page.title = "New Page Title"
+```
+
+Create new elements and compose them together:
+
+```python
+# Create simple elements.
+div = web.div("Hello, World!")
+paragraph = web.p("Some text", id="my-para", className="text-content")
+
+# Compose elements together.
+container = web.div(
+    web.h1("Title"),
+    web.p("First paragraph"),
+    web.p("Second paragraph"),
+    id="container"
+)
+
+# Add to the page.
+web.page.body.append(container)
+
+# Create with initial attributes.
+link = web.a(
+    "Click me",
+    href="https://example.com",
+    target="_blank",
+    classes=["link", "external"]
+)
+```
+
+Modify element content and attributes:
+
+```python
+# Update content.
+element.innerHTML = "<b>Bold text</b>"
+element.textContent = "Plain text"
+
+# Update attributes.
+element.id = "new-id"
+element.title = "Tooltip text"
+
+# Bulk update with convenience method.
+element.update(
+    classes=["active", "highlighted"],
+    style={"color": "red", "font-size": "16px"},
+    title="Updated tooltip"
+)
+```
+
+An element's CSS classes behave like a Python `set`:
+
+```python
+# Add and remove classes
+element.classes.add("active")
+element.classes.add("highlighted")
+element.classes.remove("hidden")
+
+# Check membership.
+if "active" in element.classes:
+    print("Element is active")
+
+# Clear all classes.
+element.classes.clear()
+
+# Discard (no error if missing).
+element.classes.discard("maybe-not-there")
+```
+
+An element's styles behave like a Python `dict`:
+
+```python
+# Set individual styles.
+element.style["color"] = "red"
+element.style["background-color"] = "#f0f0f0"
+element.style["font-size"] = "16px"
+
+# Remove a style.
+del element.style["margin"]
+
+# Check if style is set.
+if "color" in element.style:
+    print(f"Color is {element.style['color']}")
+```
+
+Update multiple elements at once via an `ElementCollection`:
+
+```python
+# Find multiple elements (returns an ElementCollection).
+items = web.page.find(".list-item")
+
+# Iterate over collection.
+for item in items:
+    item.innerHTML = "Updated"
+    item.classes.add("processed")
+
+# Bulk update all elements.
+items.update_all(
+    innerHTML="Hello",
+    className="updated-item"
+)
+
+# Index and slice collections.
+first = items[0]
+subset = items[1:3]
+
+# Get an element by ID within the collection.
+special = items["special-id"]
+
+# Find descendants within the collection.
+subitems = items.find(".sub-item")
+```
+
+Manage `select` element options (also for `datalist` and `optgroup`):
+
+```python
+# Get existing select.
+select = web.page["my-select"]
+
+# Add options.
+select.options.add(value="1", html="Option 1")
+select.options.add(value="2", html="Option 2", selected=True)
+
+# Get selected option.
+selected = select.options.selected
+print(f"Selected: {selected.value}")
+
+# Iterate over options.
+for option in select.options:
+    print(f"{option.value}: {option.innerHTML}")
+
+# Clear all options.
+select.options.clear()
+
+# Remove specific option by index.
+select.options.remove(0)
+```
+
+Attach event handlers to elements:
+
+```python
+from pyscript import when
+
+button = web.button("Click me", id="my-button")
+
+# Use the when decorator.
+@when("click", button)
+def handle_click(event):
+    print("Button clicked!")
+
+# Or add directly to the event.
+def another_handler(event):
+    print("Another handler")
+
+button.on_click.add_listener(another_handler)
+
+# Pass handler during creation.
+button = web.button("Click", on_click=handle_click)
+```
+
+All `Element` instances provide direct access to the underlying DOM element
+via attribute delegation:
+
+```python
+# Most DOM methods are accessible directly.
+element.scrollIntoView()
+element.focus()
+element.blur()
+
+# But we do have a historic convenience method for scrolling into view.
+element.show_me()  # Calls scrollIntoView()
+
+# Access the raw DOM element when needed for special cases.
+dom_element = element._dom_element
+```
+
+The main entry point is the `page` object, which represents the current
+document and provides access to common elements like `page.body` and methods
+like `page.find()` for querying the DOM.
+"""
 
 from pyscript import document, when, Event  # noqa: F401
 from pyscript.ffi import create_proxy, is_none
 
 
-def wrap_dom_element(dom_element):
-    """Wrap an existing DOM element in an instance of a subclass of `Element`.
+# Utility functions for finding and wrapping DOM elements.
+
+
+def _wrap_if_not_none(dom_element):
+    """
+    Wrap a `dom_element`, returning `None` if the element is `None`/`null`.
+    """
+    return Element.wrap_dom_element(dom_element) if not is_none(dom_element) else None
+
+
+def _find_by_id(dom_node, target_id):
+    """
+    Find an element by `id` within a `dom_node`.
+
+    The `target_id` can optionally start with '#'. Returns a wrapped `Element`
+    or `None` if not found.
+    """
+    element_id = target_id[1:] if target_id.startswith("#") else target_id
+    result = dom_node.querySelector(f"#{element_id}")
+    return _wrap_if_not_none(result)
+
 
-    This is just a convenience function to avoid having to import the `Element` class
-    and use its class method.
+def _find_and_wrap(dom_node, selector):
     """
+    Find all descendants of `dom_node` matching the CSS `selector`.
 
-    return Element.wrap_dom_element(dom_element)
+    Returns an `ElementCollection` of wrapped elements.
+    """
+    return ElementCollection.wrap_dom_elements(dom_node.querySelectorAll(selector))
 
 
 class Element:
-    # A lookup table to get an `Element` subclass by tag name. Used when wrapping an
-    # existing DOM element.
+    """
+    The base class for all [HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements).
+
+    Provides a Pythonic interface to DOM elements with support for attributes,
+    events, styles, classes, and DOM manipulation. It can create new elements
+    or wrap existing DOM elements.
+
+    Elements are typically created using the tag-specific classes found
+    within this namespace (e.g. `web.div`, `web.span`, `web.button`):
+
+    ```python
+    from pyscript import web
+
+
+    # Create a simple div.
+    div = web.div("Hello, World!")
+
+    # Create with attributes.
+    link = web.a("Click me", href="https://example.com", target="_blank")
+
+    # Create with classes and styles.
+    button = web.button(
+        "Submit",
+        classes=["primary", "large"],
+        style={"background-color": "blue", "color": "white"},
+        id="submit-btn"
+    )
+    ```
+
+    !!! info
+
+        Some elements have an underscore suffix in their class names (e.g.
+        `select_`, `input_`).
+
+        This is to avoid clashes with Python keywords. The underscore is removed
+        when determining the actual HTML tag name.
+
+    Wrap existing DOM elements found on the page:
+
+    ```python
+    # Find and wrap an element by CSS selector.
+    existing = web.page.find(".my_class")[0]
+
+    # Or, better, just use direct ID lookup (with or without the
+    # leading '#').
+    existing = web.page["my-element"]
+    ```
+
+    Element attributes are accessible as Python properties:
+
+    ```python
+    # Get attributes.
+    element_id = div.id
+    element_title = div.title
+    element_href = link.href
+
+    # Set attributes.
+    div.id = "new-id"
+    div.title = "Tooltip text"
+    link.href = "https://new-url.com"
+
+    # HTML content.
+    div.innerHTML = "<b>Bold text</b>"
+    div.textContent = "Plain text"
+    ```
+
+    CSS classes are managed through a `set`-like interface:
+
+    ```python
+    # Add classes.
+    element.classes.add("active")
+    element.classes.add("highlighted")
+
+    # Remove classes.
+    element.classes.remove("inactive")
+    element.classes.discard("maybe-missing")  # No error if absent
+
+    # Check membership.
+    if "active" in element.classes:
+        print("Element is active")
+
+    # Iterate over classes.
+    for cls in element.classes:
+        print(cls)
+    ```
+
+    Explicit CSS styles are managed through a `dict`-like interface:
+
+    ```python
+    # Set styles using CSS property names (hyphenated).
+    element.style["color"] = "red"
+    element.style["background-color"] = "#f0f0f0"
+    element.style["font-size"] = "16px"
+
+    # Get styles.
+    color = element.style["color"]
+
+    # Remove styles.
+    del element.style["margin"]
+    ```
+
+    Add, find, and navigate elements:
+
+    ```python
+    # Append children.
+    parent.append(child_element)
+    parent.append(child1, child2, child3)  # Multiple at once
+
+    # Find descendants using CSS selectors.
+    buttons = parent.find("button")
+    items = parent.find(".item-class")
+
+    # Navigate the tree.
+    child = parent.children[0]
+    parent_elem = child.parent
+
+    # Access children by index or slice.
+    first_child = parent[0]
+    first_three = parent[0:3]
+
+    # Get a child explicitly by ID. Returns None if not found.
+    specific = parent["child-id"]
+    ```
+
+    Attach event listeners to elements:
+
+    ```python
+    button = web.button("Click me")
+
+    # Use the @when decorator with event name.
+    from pyscript import when
+
+    @when("click", button)
+    def handle_click(event):
+        print("Clicked!")
+
+    # Or use the on_* event directly with @when.
+    @when(button.on_click)
+    def handle_click(event):
+        print("Also works!")
+
+    # Pass handlers during element creation.
+    button = web.button("Click", on_click=handle_click)
+    ```
+
+    Update multiple properties at once:
+
+    ```python
+    element.update(
+        classes=["active", "highlighted"],
+        style={"color": "red", "font-size": "20px"},
+        id="updated-id",
+        title="New tooltip"
+    )
+    ```
+
+    !!! warning
+        **Some HTML attributes clash with Python keywords and use trailing
+        underscores**.
+
+    Use `for_` instead of `for`, and `class_` instead of `class`.
+
+    ```python
+    # The 'for' attribute (on labels)
+    label = web.label("Username", for_="username-input")
+
+    # The 'class' attribute (although 'classes' is preferred)
+    div.class_ = "my-class"
+    ```
+
+    Create copies of elements:
+
+    ```python
+    original = web.div("Original content", id="original")
+    clone = original.clone(clone_id="cloned")
+    ```
+
+    Access the underlying DOM element when needed:
+
+    ```python
+    # Most DOM properties and methods are accessible directly.
+    element.focus()
+    element.scrollIntoView()
+    bounding_rect = element.getBoundingClientRect()
+
+    # Or access the raw DOM element.
+    dom_element = element._dom_element
+    ```
+    """
+
+    # Lookup table: tag name -> Element subclass.
     element_classes_by_tag_name = {}
 
     @classmethod
     def get_tag_name(cls):
-        """Return the HTML tag name for the class.
-
-        For classes that have a trailing underscore (because they clash with a Python
-        keyword or built-in), we remove it to get the tag name. e.g. for the `input_`
-        class, the tag name is `input`.
+        """
+        Get the HTML tag name for this class.
 
+        Classes ending with underscore (e.g. `input_`) have it removed to get
+        the actual HTML tag name.
         """
         return cls.__name__.replace("_", "")
 
     @classmethod
     def register_element_classes(cls, element_classes):
-        """Register an iterable of element classes."""
+        """
+        Register `Element` subclasses for tag-based lookup.
+        """
         for element_class in element_classes:
             tag_name = element_class.get_tag_name()
             cls.element_classes_by_tag_name[tag_name] = element_class
 
     @classmethod
     def unregister_element_classes(cls, element_classes):
-        """Unregister an iterable of element classes."""
+        """
+        Unregister `Element` subclasses from tag-based lookup.
+        """
         for element_class in element_classes:
             tag_name = element_class.get_tag_name()
             cls.element_classes_by_tag_name.pop(tag_name, None)
 
     @classmethod
     def wrap_dom_element(cls, dom_element):
-        """Wrap an existing DOM element in an instance of a subclass of `Element`.
+        """
+        Wrap a DOM element in the appropriate `Element` subclass.
 
-        We look up the `Element` subclass by the DOM element's tag name. For any unknown
-        elements (custom tags etc.) use *this* class (`Element`).
+        Looks up the subclass by tag name. Unknown tags use the base `Element`
+        class.
         """
         element_cls = cls.element_classes_by_tag_name.get(
             dom_element.tagName.lower(), cls
         )
-
         return element_cls(dom_element=dom_element)
 
     def __init__(self, dom_element=None, classes=None, style=None, **kwargs):
-        """Create a new, or wrap an existing DOM element.
-
-        If `dom_element` is None we are being called to *create* a new element.
-        Otherwise, we are being called to *wrap* an existing DOM element.
         """
-        self._dom_element = (
-            document.createElement(type(self).get_tag_name())
-            if is_none(dom_element)
-            else dom_element
-        )
+        Create or wrap a DOM element.
 
-        # HTML on_events attached to the element become pyscript.Event instances.
+        If `dom_element` is `None`, this creates a new element. Otherwise wraps
+        the provided DOM element. The `**kwargs` can include HTML attributes
+        and event handlers (names starting with `on_`).
+        """
+        # Create or wrap the DOM element.
+        if is_none(dom_element):
+            self._dom_element = document.createElement(type(self).get_tag_name())
+        else:
+            self._dom_element = dom_element
+        # Event handling.
         self._on_events = {}
-
-        # Handle kwargs for handling named events with a default handler function.
-        properties = {}
-        for name, handler in kwargs.items():
-            if name.startswith("on_"):
-                ev = self.get_event(name)  # Create the default Event instance.
-                ev.add_listener(handler)
-            else:
-                properties[name] = handler
-
-        # A set-like interface to the element's `classList`.
-        self._classes = Classes(self)
-
-        # A dict-like interface to the element's `style` attribute.
-        self._style = Style(self)
-
-        # Set any specified classes, styles, and DOM properties.
-        self.update(classes=classes, style=style, **properties)
+        self.update(classes=classes, style=style, **kwargs)
 
     def __eq__(self, obj):
-        """Check for equality by comparing the underlying DOM element."""
+        """
+        Check equality by comparing underlying DOM elements.
+        """
         return isinstance(obj, Element) and obj._dom_element == self._dom_element
 
     def __getitem__(self, key):
-        """Get an item within the element's children.
+        """
+        Get an item within this element.
 
-        If `key` is an integer or a slice we use it to index/slice the element's
-        children. Otherwise, we use `key` as a query selector.
+        Behaviour depends on the key type:
+
+        - Integer: returns the child at that index.
+        - Slice: returns a collection of children in that slice.
+        - String: looks up an element by id (with or without '#' prefix).
+
+        ```python
+        element[0]          # First child.
+        element[1:3]        # Second and third children.
+        element["my-id"]    # Element with id="my-id" (or None).
+        element["#my-id"]   # Same as above (# is optional).
+        ```
         """
+
         if isinstance(key, (int, slice)):
             return self.children[key]
-
-        return self.find(key)
+        if isinstance(key, str):
+            return _find_by_id(self._dom_element, key)
+        raise TypeError(
+            f"Element indices must be integers, slices, or strings, "
+            f"not {type(key).__name__}."
+        )
 
     def __getattr__(self, name):
         """
         Get an attribute from the element.
 
-        If the attribute is an event (e.g. "on_click"), we wrap it in an `Event`
-        instance and return that. Otherwise, we return the attribute from the
-        underlying DOM element.
+        Attributes starting with `on_` return `Event` instances. Other
+        attributes are retrieved from the underlying DOM element.
         """
         if name.startswith("on_"):
             return self.get_event(name)
-        # This allows us to get attributes on the underlying DOM element that clash
-        # with Python keywords or built-ins (e.g. the output element has an
-        # attribute `for` which is a Python keyword, so you can access it on the
-        # Element instance via `for_`).
-        if name.endswith("_"):
-            name = name[:-1]  # noqa: FURB188 No str.removesuffix() in MicroPython.
-        if name == "for":
-            # The `for` attribute is a special case as it is a keyword in both
-            # Python and JavaScript.
-            # We need to get it from the underlying DOM element as `htmlFor`.
-            name = "htmlFor"
-        return getattr(self._dom_element, name)
+        dom_name = self._normalize_attribute_name(name)
+        return getattr(self._dom_element, dom_name)
 
     def __setattr__(self, name, value):
-        # This class overrides `__setattr__` to delegate "public" attributes to the
-        # underlying DOM element. BUT, we don't use the usual Python pattern where
-        # we set attributes on the element itself via `self.__dict__` as that is not
-        # yet supported in our build of MicroPython. Instead, we handle it here by
-        # using super for all "private" attributes (those starting with an underscore).
+        """
+        Set an attribute on the element.
+
+        Private attributes (starting with `_`) are set on the Python object.
+        Public attributes are set on the underlying DOM element. Attributes
+        starting with `on_` are treated as events.
+        """
         if name.startswith("_"):
             super().__setattr__(name, value)
-
+        elif name.startswith("on_"):
+            # Separate events...
+            self.get_event(name).add_listener(value)
         else:
-            # This allows us to set attributes on the underlying DOM element that clash
-            # with Python keywords or built-ins (e.g. the output element has an
-            # attribute `for` which is a Python keyword, so you can access it on the
-            # Element instance via `for_`).
-            if name.endswith("_"):
-                name = name[:-1]  # noqa: FURB188 No str.removesuffix() in MicroPython.
-            if name == "for":
-                # The `for` attribute is a special case as it is a keyword in both
-                # Python and JavaScript.
-                # We need to set it on the underlying DOM element as `htmlFor`.
-                name = "htmlFor"
-
-            if name.startswith("on_"):
-                # Ensure on-events are cached in the _on_events dict if the
-                # user is setting them directly.
-                self._on_events[name] = value
-
-            setattr(self._dom_element, name, value)
+            # ...from regular attributes.
+            dom_name = self._normalize_attribute_name(name)
+            setattr(self._dom_element, dom_name, value)
+
+    def _normalize_attribute_name(self, name):
+        """
+        Normalize Python attribute names to DOM attribute names.
+
+        Removes trailing underscores and maps special cases.
+        """
+        if name.endswith("_"):
+            name = name[:-1]
+        if name == "for":
+            return "htmlFor"
+        if name == "class":
+            return "className"
+        return name
 
     def get_event(self, name):
         """
         Get an `Event` instance for the specified event name.
+
+        Event names must start with `on_` (e.g. `on_click`). Creates and
+        caches `Event` instances that are triggered when the DOM event fires.
         """
         if not name.startswith("on_"):
-            msg = "Event names must start with 'on_'."
-            raise ValueError(msg)
-        event_name = name[3:]  # Remove the "on_" prefix.
+            raise ValueError("Event names must start with 'on_'.")
+        event_name = name[3:]  # Remove 'on_' prefix.
         if not hasattr(self._dom_element, event_name):
-            msg = f"Element has no '{event_name}' event."
-            raise ValueError(msg)
+            raise ValueError(f"Element has no '{event_name}' event.")
         if name in self._on_events:
             return self._on_events[name]
-        # Such an on-event exists in the DOM element, but we haven't yet
-        # wrapped it in an Event instance. Let's do that now. When the
-        # underlying DOM element's event is triggered, the Event instance
-        # will be triggered too.
+        # Create Event instance and wire it to the DOM event.
         ev = Event()
         self._on_events[name] = ev
         self._dom_element.addEventListener(event_name, create_proxy(ev.trigger))
@@ -186,199 +587,307 @@ class Element:
 
     @property
     def children(self):
-        """Return the element's children as an `ElementCollection`."""
+        """
+        Return this element's children as an `ElementCollection`.
+        """
         return ElementCollection.wrap_dom_elements(self._dom_element.children)
 
     @property
     def classes(self):
-        """Return the element's `classList` as a `Classes` instance."""
+        """
+        Return the element's CSS classes as a `set`-like `Classes` object.
+
+        Supports set operations: `add`, `remove`, `discard`, `clear`.
+        Check membership with `in`, iterate with `for`, get length with `len()`.
+
+        ```python
+        element.classes.add("active")
+        if "disabled" in element.classes:
+            ...
+        ```
+        """
+        if not hasattr(self, "_classes"):
+            self._classes = Classes(self)
         return self._classes
 
+    @property
+    def style(self):
+        """
+        Return the element's CSS styles as a `dict`-like `Style` object.
+
+        Access using `dict`-style syntax with standard
+        [CSS property names (hyphenated)](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference).
+
+        ```python
+        element.style["background-color"] = "red"
+        element.style["font-size"] = "16px"
+        del element.style["margin"]
+        ```
+        """
+        if not hasattr(self, "_style"):
+            self._style = Style(self)
+        return self._style
+
     @property
     def parent(self):
-        """Return the element's `parent `Element`."""
+        """
+        Return this element's parent `Element`, or `None`.
+        """
         if is_none(self._dom_element.parentElement):
             return None
-
         return Element.wrap_dom_element(self._dom_element.parentElement)
 
-    @property
-    def style(self):
-        """Return the element's `style` attribute as a `Style` instance."""
-        return self._style
-
     def append(self, *items):
-        """Append the specified items to the element."""
+        """
+        Append items to this element's `children`.
+
+        Accepts `Element` instances, `ElementCollection` instances, lists,
+        tuples, raw DOM elements, and NodeLists.
+        """
         for item in items:
             if isinstance(item, Element):
                 self._dom_element.appendChild(item._dom_element)
-
             elif isinstance(item, ElementCollection):
                 for element in item:
                     self._dom_element.appendChild(element._dom_element)
-
-            # We check for list/tuple here and NOT for any iterable as it will match
-            # a JS Nodelist which is handled explicitly below.
-            # NodeList.
             elif isinstance(item, (list, tuple)):
                 for child in item:
                     self.append(child)
-
+            elif hasattr(item, "tagName"):
+                # Raw DOM element.
+                self._dom_element.appendChild(item)
+            elif hasattr(item, "length"):
+                # NodeList or similar iterable.
+                for element in item:
+                    self._dom_element.appendChild(element)
             else:
-                # In this case we know it's not an Element or an ElementCollection, so
-                # we guess that it's either a DOM element or NodeList returned via the
-                # ffi.
-                try:
-                    # First, we try to see if it's an element by accessing the 'tagName'
-                    # attribute.
-                    item.tagName
-                    self._dom_element.appendChild(item)
-
-                except AttributeError:
-                    try:
-                        # Ok, it's not an element, so let's see if it's a NodeList by
-                        # accessing the 'length' attribute.
-                        item.length
-                        for element_ in item:
-                            self._dom_element.appendChild(element_)
-
-                    except AttributeError:
-                        # Nope! This is not an element or a NodeList.
-                        msg = (
-                            f'Element "{item}" is a proxy object, "'
-                            f"but not a valid element or a NodeList."
-                        )
-                        raise TypeError(msg)
+                raise TypeError(f"Cannot append {type(item).__name__} to element.")
 
     def clone(self, clone_id=None):
-        """Make a clone of the element (clones the underlying DOM object too)."""
+        """
+        Clone this element and its underlying DOM element.
+
+        Optionally assign a new `id` to the clone.
+        """
         clone = Element.wrap_dom_element(self._dom_element.cloneNode(True))
         clone.id = clone_id
         return clone
 
     def find(self, selector):
-        """Find all elements that match the specified selector.
+        """
+        Find all descendant elements matching the
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
-        Return the results as a (possibly empty) `ElementCollection`.
+        Returns an `ElementCollection` (possibly empty).
+
+        ```python
+        element.find("div")              # All div descendants.
+        element.find(".my-class")        # All elements with class.
+        element.find("#my-id")           # Element with id (as collection).
+        element.find("div.my-class")     # All divs with class.
+        ```
         """
-        return ElementCollection.wrap_dom_elements(
-            self._dom_element.querySelectorAll(selector)
-        )
+        return _find_and_wrap(self._dom_element, selector)
 
     def show_me(self):
-        """Convenience method for 'element.scrollIntoView()'."""
+        """
+        Scroll this element into view.
+        """
         self._dom_element.scrollIntoView()
 
     def update(self, classes=None, style=None, **kwargs):
-        """Update the element with the specified classes, styles, and DOM properties."""
+        """
+        Update this element's `classes`, `style`, and `attributes`
+        (via arbitrary `**kwargs`).
 
+        Convenience method for bulk updates.
+        """
         if classes:
-            self.classes.add(classes)
-
+            if isinstance(classes, str):
+                self.classes.add(classes)
+            else:
+                for class_name in classes:
+                    self.classes.add(class_name)
         if style:
-            self.style.set(**style)
-
+            for key, value in style.items():
+                self.style[key] = value
         for name, value in kwargs.items():
             setattr(self, name, value)
 
 
-class Classes:
-    """A set-like interface to an element's `classList`."""
+class Classes(set):
+    """
+    Behaves like a Python `set` with changes automatically reflected in the
+    element's `classList`.
+
+    ```python
+    # Add and remove classes.
+    element.classes.add("active")
+    element.classes.remove("inactive")
+    element.classes.discard("maybe-missing")  # No error if absent.
+
+    # Check membership.
+    if "active" in element.classes:
+        print("Element is active")
+
+    # Clear all classes.
+    element.classes.clear()
+
+    # Iterate over classes.
+    for cls in element.classes:
+        print(cls)
+    ```
+    """
 
-    def __init__(self, element: Element):
-        self._element = element
-        self._class_list = self._element._dom_element.classList
+    def __init__(self, element):
+        """Initialise the Classes set for the given element."""
+        self._class_list = element._dom_element.classList
+        super().__init__(self._class_list)
 
-    def __contains__(self, item):
-        return item in self._class_list
+    def _extract_class_names(self, class_name):
+        """
+        If the class_name contains several class names separated by spaces,
+        split them and return as a list. Otherwise, return the class_name as is
+        in a list.
+        """
+        return (
+            [name for name in class_name.split() if name]
+            if " " in class_name
+            else [class_name]
+        )
 
-    def __eq__(self, other):
-        # We allow comparison with either another `Classes` instance...
-        if isinstance(other, Classes):
-            compare_with = list(other._class_list)
+    def add(self, class_name):
+        """Add a class."""
+        for name in self._extract_class_names(class_name):
+            super().add(name)
+            self._class_list.add(name)
+
+    def remove(self, class_name):
+        """Remove a class."""
+        for name in self._extract_class_names(class_name):
+            super().remove(name)
+            self._class_list.remove(name)
+
+    def discard(self, class_name):
+        """Remove a class if present."""
+        for name in self._extract_class_names(class_name):
+            super().discard(name)
+            if name in self._class_list:
+                self._class_list.remove(name)
 
-        # ...or iterables of strings.
-        else:
-            # TODO: Check MP for existence of better iterable test.
-            try:
-                compare_with = iter(other)
+    def clear(self):
+        """Remove all classes."""
+        super().clear()
+        while self._class_list.length > 0:
+            self._class_list.remove(self._class_list.item(0))
 
-            except TypeError:
-                return False
 
-        return set(self._class_list) == set(compare_with)
+class Style(dict):
+    """
+    Behaves like a Python `dict` with changes automatically reflected in the
+    element's `style` attribute.
 
-    def __iter__(self):
-        return iter(self._class_list)
+    ```python
+    # Set and get styles using CSS property names (hyphenated).
+    element.style["color"] = "red"
+    element.style["background-color"] = "#f0f0f0"
+    element.style["font-size"] = "16px"
 
-    def __len__(self):
-        return self._class_list.length
+    # Get a style value.
+    color = element.style["color"]
 
-    def __repr__(self):
-        return f"Classes({', '.join(self._class_list)})"
+    # Remove a style.
+    del element.style["margin"]
 
-    def __str__(self):
-        return " ".join(self._class_list)
+    # Check if a style is set.
+    if "color" in element.style:
+        print(f"Color is {element.style['color']}")
+    ```
+    """
 
-    def add(self, *class_names):
-        """Add one or more classes to the element."""
-        for class_name in class_names:
-            if isinstance(class_name, list):
-                for item in class_name:
-                    self.add(item)
+    def __init__(self, element):
+        """Initialise the Style dict for the given element."""
+        self._style = element._dom_element.style
+        super().__init__()
 
-            else:
-                self._class_list.add(class_name)
+    def __setitem__(self, key, value):
+        """Set a style property."""
+        super().__setitem__(key, value)
+        self._style.setProperty(key, str(value))
 
-    def contains(self, class_name):
-        """Check if the element has the specified class."""
-        return class_name in self
+    def __delitem__(self, key):
+        """Remove a style property."""
+        super().__delitem__(key)
+        self._style.removeProperty(key)
 
-    def remove(self, *class_names):
-        """Remove one or more classes from the element."""
-        for class_name in class_names:
-            if isinstance(class_name, list):
-                for item in class_name:
-                    self.remove(item)
 
-            else:
-                self._class_list.remove(class_name)
+class HasOptions:
+    """
+    Mixin for elements with options (`datalist`, `optgroup`, `select`).
 
-    def replace(self, old_class, new_class):
-        """Replace one of the element's classes with another."""
-        self.remove(old_class)
-        self.add(new_class)
+    Provides an `options` property that returns an `Options` instance. Used
+    in conjunction with the `Options` class.
 
-    def toggle(self, *class_names):
-        """Toggle one or more of the element's classes."""
-        for class_name in class_names:
-            if class_name in self:
-                self.remove(class_name)
+    ```python
+    # Get a select element and work with its options.
+    select = web.page["my-select"]
 
-            else:
-                self.add(class_name)
+    # Add options.
+    select.options.add(value="1", html="Option 1")
+    select.options.add(value="2", html="Option 2", selected=True)
 
+    # Get the selected option.
+    selected = select.options.selected
 
-class HasOptions:
-    """Mix-in for elements that have an options attribute.
+    # Iterate over options.
+    for option in select.options:
+        print(f"{option.value}: {option.innerHTML}")
 
-    The elements that support options are: <datalist>, <optgroup>, and <select>.
+    # Clear all options.
+    select.options.clear()
+    ```
     """
 
     @property
     def options(self):
-        """Return the element's options as an `Options"""
+        """Return this element's options as an `Options` instance."""
         if not hasattr(self, "_options"):
             self._options = Options(self)
-
         return self._options
 
 
 class Options:
-    """This class represents the <option>s of a <datalist>, <optgroup> or <select>.
+    """
+    Interface to the options of a `datalist`, `optgroup`, or `select` element.
+
+    Supports adding, removing, and accessing option elements. Used in
+    conjunction with the `HasOptions` mixin.
+
+    ```python
+    # Add options to a select element.
+    select.options.add(value="1", html="Option 1")
+    select.options.add(value="2", html="Option 2", selected=True)
+
+    # Insert option at specific position.
+    select.options.add(value="1.5", html="Option 1.5", before=1)
+
+    # Access options by index.
+    first_option = select.options[0]
+
+    # Get the selected option.
+    selected = select.options.selected
+    print(f"Selected: {selected.value}")
+
+    # Iterate over all options.
+    for option in select.options:
+        print(option.innerHTML)
+
+    # Remove option by index.
+    select.options.remove(0)
 
-    It allows access to add and remove <option>s by using the `add`, `remove` and
-    `clear` methods.
+    # Clear all options.
+    select.options.clear()
+    ```
     """
 
     def __init__(self, element):
@@ -394,30 +903,39 @@ class Options:
         return len(self.options)
 
     def __repr__(self):
-        return f"{self.__class__.__name__} (length: {len(self)}) {self.options}"
+        return f"{self.__class__.__name__} (length: {len(self)}) " f"{self.options}"
 
     @property
     def options(self):
-        """Return the list of options."""
+        """
+        Return the list of option elements.
+        """
         return [Element.wrap_dom_element(o) for o in self._element._dom_element.options]
 
     @property
     def selected(self):
-        """Return the selected option."""
+        """
+        Return the currently selected option.
+        """
         return self.options[self._element._dom_element.selectedIndex]
 
     def add(self, value=None, html=None, text=None, before=None, **kwargs):
-        """Add a new option to the element"""
-        if value is not None:
-            kwargs["value"] = value
+        """
+        Add a new option to the element.
 
-        if html is not None:
+        Can specify `value`, `html` content, and `text`. The `before` parameter can
+        be an `Element` or index to insert before. The `**kwargs` are additional
+        arbitrary attributes for the new option element.
+        """
+        if value:
+            kwargs["value"] = value
+        if html:
             kwargs["innerHTML"] = html
-
-        if text is not None:
+        if text:
             kwargs["text"] = text
 
-        new_option = option(**kwargs)
+        # The `option` element class is dynamically created below.
+        new_option = option(**kwargs)  # noqa: F821
 
         if before and isinstance(before, Element):
             before = before._dom_element
@@ -425,56 +943,62 @@ class Options:
         self._element._dom_element.add(new_option._dom_element, before)
 
     def clear(self):
-        """Remove all options."""
-        while len(self) > 0:
-            self.remove(0)
+        """
+        Remove all options.
+        """
+        self._element._dom_element.length = 0
 
     def remove(self, index):
-        """Remove the option at the specified index."""
+        """
+        Remove the option at the specified `index`.
+        """
         self._element._dom_element.remove(index)
 
 
-class Style:
-    """A dict-like interface to an element's `style` attribute."""
-
-    def __init__(self, element: Element):
-        self._element = element
-        self._style = self._element._dom_element.style
-
-    def __getitem__(self, key):
-        return self._style.getPropertyValue(key)
+class ContainerElement(Element):
+    """
+    Base class for elements that can contain other elements.
 
-    def __setitem__(self, key, value):
-        self._style.setProperty(key, value)
+    Extends `Element` with convenient child handling during initialization.
 
-    def remove(self, key):
-        """Remove a CSS property from the element."""
-        self._style.removeProperty(key)
+    ```python
+    from pyscript import web
 
-    def set(self, **kwargs):
-        """Set one or more CSS properties on the element."""
-        for key, value in kwargs.items():
-            self._element._dom_element.style.setProperty(key, value)
 
-    # CSS Properties
-    # Reference: https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts#L3799C1-L5005C2
-    # Following properties automatically generated from the above reference using
-    # tools/codegen_css_proxy.py
-    @property
-    def visible(self):
-        return self._element._dom_element.style.visibility
+    # Create with child elements as arguments.
+    div = web.div(
+        web.h1("Title"),
+        web.p("Paragraph 1"),
+        web.p("Paragraph 2")
+    )
 
-    @visible.setter
-    def visible(self, value):
-        self._element._dom_element.style.visibility = value
+    # Or use the children keyword argument.
+    div = web.div(children=[web.p("Child 1"), web.p("Child 2")])
 
+    # Mix elements and HTML strings.
+    div = web.div(
+        web.h1("Title"),
+        "<p>HTML content</p>",
+        web.button("Click me")
+    )
 
-class ContainerElement(Element):
-    """Base class for elements that can contain other elements."""
+    # Iterate over children.
+    for child in div:
+        print(child.innerHTML)
+    ```
+    """
 
     def __init__(
         self, *args, children=None, dom_element=None, style=None, classes=None, **kwargs
     ):
+        """
+        Create a container element with optional `children`.
+
+        Children can be passed as positional `*args` or via the `children`
+        keyword argument. String children are inserted as unescaped HTML. The
+        `style`, `classes`, and `**kwargs` are passed to the base `Element`
+        initializer.
+        """
         super().__init__(
             dom_element=dom_element, style=style, classes=classes, **kwargs
         )
@@ -482,7 +1006,6 @@ class ContainerElement(Element):
         for child in list(args) + (children or []):
             if isinstance(child, (Element, ElementCollection)):
                 self.append(child)
-
             else:
                 self._dom_element.insertAdjacentHTML("beforeend", child)
 
@@ -490,124 +1013,93 @@ class ContainerElement(Element):
         yield from self.children
 
 
-class ClassesCollection:
-    """A set-like interface to the classes of the elements in a collection."""
-
-    def __init__(self, collection):
-        self._collection = collection
-
-    def __contains__(self, class_name):
-        for element in self._collection:
-            if class_name in element.classes:
-                return True
-
-        return False
-
-    def __eq__(self, other):
-        return (
-            isinstance(other, ClassesCollection)
-            and self._collection == other._collection
-        )
+class ElementCollection:
+    """
+    A collection of Element instances with `list`-like operations.
 
-    def __iter__(self):
-        yield from self._all_class_names()
+    Supports iteration, indexing, slicing, and finding descendants.
+    For bulk operations, iterate over the collection explicitly or use
+    the `update_all` method.
 
-    def __len__(self):
-        return len(self._all_class_names())
+    ```python
+    # Get a collection of elements.
+    items = web.page.find(".item")
 
-    def __repr__(self):
-        return f"ClassesCollection({self._collection!r})"
+    # Access by index.
+    first = items[0]
+    last = items[-1]
 
-    def __str__(self):
-        return " ".join(self._all_class_names())
+    # Slice the collection.
+    subset = items[1:3]
 
-    def add(self, *class_names):
-        """Add one or more classes to the elements in the collection."""
-        for element in self._collection:
-            element.classes.add(*class_names)
+    # Look up a specific element by id (returns None if not found).
+    specific = items["item-id"]
 
-    def contains(self, class_name):
-        """Check if any element in the collection has the specified class."""
-        return class_name in self
+    # Iterate over elements.
+    for item in items:
+        item.innerHTML = "Updated"
+        item.classes.add("processed")
 
-    def remove(self, *class_names):
-        """Remove one or more classes from the elements in the collection."""
+    # Bulk update all contained elements.
+    items.update_all(innerHTML="Hello", className="updated")
 
-        for element in self._collection:
-            element.classes.remove(*class_names)
+    # Find matches within the collection.
+    buttons = items.find("button")
 
-    def replace(self, old_class, new_class):
-        """Replace one of the classes in the elements in the collection with another."""
-        for element in self._collection:
-            element.classes.replace(old_class, new_class)
+    # Get the count.
+    count = len(items)
+    ```
+    """
 
-    def toggle(self, *class_names):
-        """Toggle one or more classes on the elements in the collection."""
-        for element in self._collection:
-            element.classes.toggle(*class_names)
-
-    def _all_class_names(self):
-        all_class_names = set()
-        for element in self._collection:
-            for class_name in element.classes:
-                all_class_names.add(class_name)
-
-        return all_class_names
-
-
-class StyleCollection:
-    """A dict-like interface to the styles of the elements in a collection."""
-
-    def __init__(self, collection):
-        self._collection = collection
-
-    def __getitem__(self, key):
-        return [element.style[key] for element in self._collection._elements]
-
-    def __setitem__(self, key, value):
-        for element in self._collection._elements:
-            element.style[key] = value
-
-    def __repr__(self):
-        return f"StyleCollection({self._collection!r})"
-
-    def remove(self, key):
-        """Remove a CSS property from the elements in the collection."""
-        for element in self._collection._elements:
-            element.style.remove(key)
-
-
-class ElementCollection:
     @classmethod
     def wrap_dom_elements(cls, dom_elements):
-        """Wrap an iterable of dom_elements in an `ElementCollection`."""
-
+        """
+        Wrap an iterable of DOM elements in an `ElementCollection`.
+        """
         return cls(
             [Element.wrap_dom_element(dom_element) for dom_element in dom_elements]
         )
 
-    def __init__(self, elements: [Element]):
+    def __init__(self, elements):
         self._elements = elements
-        self._classes = ClassesCollection(self)
-        self._style = StyleCollection(self)
 
     def __eq__(self, obj):
-        """Check for equality by comparing the underlying DOM elements."""
+        """
+        Check equality by comparing elements.
+        """
         return isinstance(obj, ElementCollection) and obj._elements == self._elements
 
     def __getitem__(self, key):
-        """Get an item in the collection.
+        """
+        Get items from the collection.
 
-        If `key` is an integer or a slice we use it to index/slice the collection.
-        Otherwise, we use `key` as a query selector.
+        Behaviour depends on the key type:
+
+        - Integer: returns the element at that index.
+        - Slice: returns a new collection with elements in that slice.
+        - String: looks up an element by id (with or without '#' prefix).
+
+        ```python
+        collection[0]          # First element.
+        collection[1:3]        # New collection with 2nd and 3rd elements.
+        collection["my-id"]    # Element with id="my-id" (or None).
+        collection["#my-id"]   # Same as above (# is optional).
+        ```
         """
         if isinstance(key, int):
             return self._elements[key]
-
         if isinstance(key, slice):
             return ElementCollection(self._elements[key])
-
-        return self.find(key)
+        if isinstance(key, str):
+            for element in self._elements:
+                result = _find_by_id(element._dom_element, key)
+                if result:
+                    return result
+            return None
+        raise TypeError(
+            f"Collection indices must be integers, slices, or strings, "
+            f"not {type(key).__name__}"
+        )
 
     def __iter__(self):
         yield from self._elements
@@ -621,621 +1113,327 @@ class ElementCollection:
             f"{self._elements}"
         )
 
-    def __getattr__(self, name):
-        return [getattr(element, name) for element in self._elements]
-
-    def __setattr__(self, name, value):
-        # This class overrides `__setattr__` to delegate "public" attributes to the
-        # elements in the collection. BUT, we don't use the usual Python pattern where
-        # we set attributes on the collection itself via `self.__dict__` as that is not
-        # yet supported in our build of MicroPython. Instead, we handle it here by
-        # using super for all "private" attributes (those starting with an underscore).
-        if name.startswith("_"):
-            super().__setattr__(name, value)
-
-        else:
-            for element in self._elements:
-                setattr(element, name, value)
-
-    @property
-    def classes(self):
-        """Return the classes of the elements in the collection as a `ClassesCollection`."""
-        return self._classes
-
     @property
     def elements(self):
-        """Return the elements in the collection as a list."""
+        """
+        Return the underlying `list` of elements.
+        """
         return self._elements
 
-    @property
-    def style(self):
-        """"""
-        return self._style
-
     def find(self, selector):
-        """Find all elements that match the specified selector.
+        """
+        Find all descendants matching the
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
 
-        Return the results as a (possibly empty) `ElementCollection`.
+        Searches within all elements in the collection.
+
+        ```python
+        collection.find("div")           # All div descendants.
+        collection.find(".my-class")     # All elements with class.
+        collection.find("#my-id")        # Element with id (as collection).
+        ```
         """
         elements = []
         for element in self._elements:
-            elements.extend(element.find(selector))
-
+            elements.extend(_find_and_wrap(element._dom_element, selector))
         return ElementCollection(elements)
 
+    def update_all(self, **kwargs):
+        """
+        Explicitly update all elements with the given attributes.
 
-# Classes for every HTML element. If the element tag name (e.g. "input") clashes with
-# either a Python keyword or common symbol, then we suffix the class name with an "_"
-# (e.g. the class for the "input" element is "input_").
-
-
-class a(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a"""
-
-
-class abbr(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr"""
-
-
-class address(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address"""
-
-
-class area(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area"""
-
-
-class article(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article"""
-
-
-class aside(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside"""
-
-
-class audio(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio"""
-
-
-class b(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b"""
-
-
-class base(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base"""
-
-
-class blockquote(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote"""
-
-
-class body(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body"""
-
-
-class br(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/br"""
+        ```python
+        collection.update_all(innerHTML="Hello")
+        collection.update_all(className="active", title="Updated")
+        ```
+        """
+        for element in self._elements:
+            for name, value in kwargs.items():
+                setattr(element, name, value)
 
 
-class button(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button"""
+# Special elements with custom methods and mixins.
 
 
 class canvas(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas"""
-
-    def download(self, filename: str = "snapped.png"):
-        """Download the current element with the filename provided in input.
-
-        Inputs:
-            * filename (str): name of the file being downloaded
+    """
+    A bespoke
+    [HTML canvas element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas)
+    with Pythonic drawing and download capabilities.
+    """
 
-        Output:
-            None
+    def download(self, filename="snapped.png"):
         """
-        download_link = a(download=filename, href=self._dom_element.toDataURL())
+        Download the canvas content as an image file.
 
-        # Adding the link to the DOM is recommended for browser compatibility to make
-        # sure that the click works.
+        Creates a temporary download link and triggers it.
+        """
+        # The `a` element class is dynamically created below.
+        download_link = a(  # noqa: F821
+            download=filename, href=self._dom_element.toDataURL()
+        )
         self.append(download_link)
-
         download_link._dom_element.click()
 
     def draw(self, what, width=None, height=None):
-        """Draw `what` on the current element
-
-        Inputs:
+        """
+        Draw a 2d image source (`what`) onto the canvas. Optionally scale to
+        `width` and `height`.
 
-            * what (canvas image source): An element to draw into the context. The
-                specification permits any canvas image source, specifically, an
-                HTMLImageElement, an SVGImageElement, an HTMLVideoElement,
-                an HTMLCanvasElement, an ImageBitmap, an OffscreenCanvas, or a
-                VideoFrame.
+        Accepts canvas image sources: `HTMLImageElement`, `SVGImageElement`,
+        `HTMLVideoElement`, `HTMLCanvasElement`, `ImageBitmap`,
+        `OffscreenCanvas`, or `VideoFrame`.
         """
         if isinstance(what, Element):
             what = what._dom_element
 
-        # https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage
         ctx = self._dom_element.getContext("2d")
         if width or height:
             ctx.drawImage(what, 0, 0, width, height)
-
         else:
             ctx.drawImage(what, 0, 0)
 
 
-class caption(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption"""
-
-
-class cite(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite"""
-
-
-class code(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code"""
-
-
-class col(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/col"""
-
-
-class colgroup(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/colgroup"""
+class video(ContainerElement):
+    """
+    A bespoke
+    [HTML video element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video)
+    with Pythonic snapshot capability (to render an image to a canvas).
+    """
 
+    def snap(self, to=None, width=None, height=None):
+        """
+        Capture a video frame `to` a canvas element. Optionally scale to
+        `width` and `height`.
 
-class data(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/data"""
+        If no canvas is provided, this will create one. The to parameter
+        can be a canvas Element, raw DOM canvas, or CSS selector string.
+        """
+        width = width if width else self.videoWidth
+        height = height if height else self.videoHeight
+        if is_none(to):
+            to = canvas(width=width, height=height)
+        elif isinstance(to, Element):
+            if to.tag != "canvas":
+                raise TypeError("Element to snap to must be a canvas.")
+        elif getattr(to, "tagName", "") == "CANVAS":
+            to = canvas(dom_element=to)
+        elif isinstance(to, str):
+            nodelist = document.querySelectorAll(to)
+            if nodelist.length == 0:
+                raise TypeError(f"No element with selector {to} to snap to.")
+            if nodelist[0].tagName != "CANVAS":
+                raise TypeError("Element to snap to must be a canvas.")
+            to = canvas(dom_element=nodelist[0])
+        to.draw(self, width, height)
+        return to
 
 
 class datalist(ContainerElement, HasOptions):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist"""
-
-
-class dd(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd"""
-
-
-class del_(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del"""
-
-
-class details(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details"""
-
-
-class dialog(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog"""
-
-
-class div(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div"""
-
-
-class dl(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl"""
-
-
-class dt(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt"""
-
-
-class em(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em"""
-
-
-class embed(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed"""
-
-
-class fieldset(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset"""
-
-
-class figcaption(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption"""
-
-
-class figure(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure"""
-
-
-class footer(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer"""
-
-
-class form(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form"""
-
-
-class h1(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h1"""
-
-
-class h2(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h2"""
-
-
-class h3(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h3"""
-
-
-class h4(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h4"""
-
-
-class h5(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h5"""
-
-
-class h6(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h6"""
-
-
-class head(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head"""
-
-
-class header(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header"""
-
-
-class hgroup(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hgroup"""
-
-
-class hr(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr"""
-
-
-class html(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html"""
-
-
-class i(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i"""
-
-
-class iframe(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe"""
-
-
-class img(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img"""
-
-
-class input_(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input"""
-
-
-class ins(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins"""
-
-
-class kbd(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd"""
-
-
-class label(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label"""
-
-
-class legend(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend"""
-
-
-class li(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li"""
-
-
-class link(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link"""
-
-
-class main(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main"""
-
-
-class map_(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/map"""
-
-
-class mark(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark"""
-
-
-class menu(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/menu"""
-
-
-class meta(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta"""
-
-
-class meter(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meter"""
-
-
-class nav(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav"""
-
-
-class object_(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object"""
-
+    """
+    HTML datalist element with options support.
 
-class ol(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol"""
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/datalist
+    """
 
 
 class optgroup(ContainerElement, HasOptions):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup"""
-
-
-class option(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option"""
-
-
-class output(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/output"""
-
-
-class p(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p"""
-
-
-class param(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/param"""
-
-
-class picture(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture"""
-
-
-class pre(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre"""
-
-
-class progress(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress"""
-
-
-class q(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q"""
-
-
-class s(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s"""
-
-
-class script(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script"""
-
+    """
+    HTML optgroup element with options support.
 
-class section(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section"""
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup
+    """
 
 
 class select(ContainerElement, HasOptions):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select"""
-
-
-class small(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small"""
-
-
-class source(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/source"""
-
-
-class span(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span"""
-
-
-class strong(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong"""
-
-
-class style(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style"""
-
-
-class sub(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub"""
-
-
-class summary(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary"""
-
-
-class sup(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup"""
-
-
-class table(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table"""
-
-
-class tbody(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tbody"""
-
-
-class td(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td"""
-
-
-class template(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template"""
-
-
-class textarea(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea"""
-
-
-class tfoot(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tfoot"""
-
-
-class th(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th"""
-
-
-class thead(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/thead"""
-
-
-class time(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time"""
-
-
-class title(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title"""
-
-
-class tr(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tr"""
-
-
-class track(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track"""
-
-
-class u(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u"""
-
-
-class ul(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul"""
-
-
-class var(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var"""
-
-
-class video(ContainerElement):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video"""
-
-    def snap(
-        self,
-        to: Element | str = None,
-        width: int | None = None,
-        height: int | None = None,
-    ):
-        """
-        Capture a snapshot (i.e. a single frame) of a video to a canvas.
+    """
+    HTML select element with options support.
 
-        Inputs:
+    Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select
+    """
 
-            * to: the canvas to save the video frame to (if None, one is created).
-            * width: width of the snapshot (defaults to the video width).
-            * height: height of the snapshot (defaults to the video height).
 
-        Output:
-            (Element) canvas element where the video frame snapshot was drawn into
-        """
-        width = width if width is not None else self.videoWidth
-        height = height if height is not None else self.videoHeight
+# Container elements that can have children.
+# Note: canvas, video, datalist, optgroup, and select are defined above
+# with special implementations due to the HasOptions mixin.
+# fmt: off
+CONTAINER_TAGS = [
+    "a", "abbr", "address", "article", "aside", "audio",
+    "b", "blockquote", "body", "button",
+    "caption", "cite", "code", "colgroup",
+    "data", "dd", "del", "details", "dialog", "div", "dl", "dt",
+    "em",
+    "fieldset", "figcaption", "figure", "footer", "form",
+    "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup", "html",
+    "i", "iframe", "ins",
+    "kbd",
+    "label", "legend", "li",
+    "main", "map", "mark", "menu", "meta", "meter",
+    "nav",
+    "object", "ol", "option", "output",
+    "p", "param", "picture", "pre", "progress",
+    "q",
+    "s", "script", "section", "small", "span", "strong", "style",
+    "sub", "summary", "sup",
+    "table", "tbody", "td", "template", "textarea", "tfoot", "th", "thead",
+    "time", "title", "tr",
+    "u", "ul",
+    "var",
+    "wbr",
+]
+"""
+Container elements that can have children. Each becomes a class in the
+`pyscript.web` namespace and corresponds to an HTML tag.
+"""
+# fmt: on
 
-        if is_none(to):
-            to = canvas(width=width, height=height)
+# Void elements that cannot have children.
+VOID_TAGS = [
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "source",
+    "track",
+]
+"""
+Void elements that cannot have children. Each becomes a class in the
+`pyscript.web` namespace and corresponds to an HTML tag.
+"""
 
-        elif isinstance(to, Element):
-            if to.tag != "canvas":
-                msg = "Element to snap to must be a canvas."
-                raise TypeError(msg)
 
-        elif getattr(to, "tagName", "") == "CANVAS":
-            to = canvas(dom_element=to)
+def _create_element_classes():
+    """
+    Create element classes dynamically and register them.
 
-        # If 'to' is a string, then assume it is a query selector.
-        elif isinstance(to, str):
-            nodelist = document.querySelectorAll(to)  # NOQA
-            if nodelist.length == 0:
-                msg = "No element with selector {to} to snap to."
-                raise TypeError(msg)
+    Generates classes for all standard HTML elements, using the appropriate
+    base class (ContainerElement or Element) for each tag.
+    """
+    # The existing special element classes defined above.
+    classes = [canvas, video, datalist, optgroup, select]
+    for tag in CONTAINER_TAGS:
+        # Tags that clash with Python keywords get a trailing underscore.
+        class_name = f"{tag}_" if tag in ("del", "map", "object") else tag
+        doc = (
+            f"HTML <{tag}> element. "
+            f"Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/"
+            f"Element/{tag}"
+        )
+        cls = type(class_name, (ContainerElement,), {"__doc__": doc})
+        globals()[class_name] = cls
+        classes.append(cls)
+    for tag in VOID_TAGS:
+        class_name = f"{tag}_" if tag == "input" else tag
+        doc = (
+            f"HTML <{tag}> element. "
+            f"Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/"
+            f"Element/{tag}"
+        )
+        cls = type(class_name, (Element,), {"__doc__": doc})
+        globals()[class_name] = cls
+        classes.append(cls)
+    Element.register_element_classes(classes)
 
-            if nodelist[0].tagName != "CANVAS":
-                msg = "Element to snap to must be a canvas."
-                raise TypeError(msg)
 
-            to = canvas(dom_element=nodelist[0])
+# Initialize element classes at module load time. :-)
+_create_element_classes()
 
-        to.draw(self, width, height)
 
-        return to
+class Page:
+    """
+    Represents the current web page.
 
+    Provides access to the document's `html`, `head`, and `body` elements,
+    plus convenience methods for finding elements and appending to the body.
 
-class wbr(Element):
-    """Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr"""
+    ```python
+    from pyscript import web
 
 
-# fmt: off
-ELEMENT_CLASSES = [
-    a, abbr, address, area, article, aside, audio,
-    b, base, blockquote, body, br, button,
-    canvas, caption, cite, code, col, colgroup,
-    data, datalist, dd, del_, details, dialog, div, dl, dt,
-    em, embed,
-    fieldset, figcaption, figure, footer, form,
-    h1, h2, h3, h4, h5, h6, head, header, hgroup, hr, html,
-    i, iframe, img, input_, ins,
-    kbd,
-    label, legend, li, link,
-    main, map_, mark, menu, meta, meter,
-    nav,
-    object_, ol, optgroup, option, output,
-    p, param, picture, pre, progress,
-    q,
-    s, script, section, select, small, source, span, strong, style, sub, summary, sup,
-    table, tbody, td, template, textarea, tfoot, th, thead, time, title, tr, track,
-    u, ul,
-    var, video,
-    wbr,
-]
-# fmt: on
+    # Access page structure.
+    web.page.html  # The <html> element.
+    web.page.head  # The <head> element.
+    web.page.body  # The <body> element.
 
+    # Get and set page title.
+    web.page.title = "New Title"
+    print(web.page.title)
 
-# Register all the default (aka "built-in") Element classes.
-Element.register_element_classes(ELEMENT_CLASSES)
+    # Find elements by CSS selector.
+    divs = web.page.find("div")
+    items = web.page.find(".item-class")
 
+    # Look up element by id.
+    element = web.page["my-id"]
+    element = web.page["#my-id"]  # The "#" prefix is optional.
 
-class Page:
-    """Represents the whole page."""
+    # Append to the body (shortcut for page.body.append).
+    web.page.append(web.div("Hello"))
+    ```
+    """
 
     def __init__(self):
         self.html = Element.wrap_dom_element(document.documentElement)
         self.body = Element.wrap_dom_element(document.body)
         self.head = Element.wrap_dom_element(document.head)
 
-    def __getitem__(self, selector):
-        """Get an item on the page.
+    def __getitem__(self, key):
+        """
+        Look up an element by id.
+
+        The '#' prefix is optional and will be stripped if present.
+        Returns None if no element with that id exists.
 
-        We don't index/slice the page like we do with `Element` and `ElementCollection`
-        as it is a bit muddier what the ideal behavior should be. Instead, we simply
-        use this as a convenience method to `find` elements on the page.
+        ```python
+        page["my-id"]      # Element with id="my-id" (or None)
+        page["#my-id"]     # Same as above (# is optional)
+        ```
         """
-        return self.find(selector)
+        return _find_by_id(document, key)
 
     @property
     def title(self):
-        """Return the page title."""
+        """
+        Get the page `title`.
+        """
         return document.title
 
     @title.setter
     def title(self, value):
-        """Set the page title."""
+        """
+        Set the page `title`.
+        """
         document.title = value
 
     def append(self, *items):
-        """Shortcut for `page.body.append`."""
+        """
+        Append items to the page `body`.
+
+        Shortcut for `page.body.append(*items)`.
+        """
         self.body.append(*items)
 
-    def find(self, selector):  # NOQA
-        """Find all elements that match the specified selector.
+    def find(self, selector):
+        """
+        Find all elements matching the
+        [CSS `selector`](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors).
+
+        Returns an `ElementCollection` of matching elements.
 
-        Return the results as a (possibly empty) `ElementCollection`.
+        ```python
+        page.find("div")              # All divs on the page
+        page.find(".my-class")        # All elements with class
+        page.find("#my-id")           # Element with id (as collection)
+        page.find("div.my-class")     # All divs with class
+        ```
         """
-        return ElementCollection.wrap_dom_elements(document.querySelectorAll(selector))
+        return _find_and_wrap(document, selector)
 
 
 page = Page()
+"""A reference to the current web page. An instance of the `Page` class."""