Update pyscript.web docs.

Author: ntoll

docs/api.md

@@ -413,29 +413,34 @@ store = await storage("my-data-store", storage_class=MyStorage)
 
 ### `pyscript.web`
 
-TODO: Use `display(element)` not `element.display()`.
-
 The classes and references in this namespace provide a Pythonic way to interact
 with the DOM. An explanation for how to idiomatically use this API can be found
 [in the user guide](../user-guide/dom/#pyscriptweb)
 
-#### `pyscript.web.dom`
+#### `pyscript.web.page`
 
-This object has two attributes and a single method:
+This object represents a web page. It has four attributes and two methods:
 
+* `html` - a reference to a Python object representing the [document's html](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html) root element.
 * `head` - a reference to a Python object representing the [document's head](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head).
 * `body` - a reference to a Python object representing the [document's body](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body).
+* `title` - the page's [title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) (usually displayed in the browser's title bar or a page's tab.
 * `find` - a method that takes a single [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)
   argument and returns a collection of Python objects representing the matching
   elements.
+* `append` - a shortcut for `page.body.append` (to add new elements to the
+  page).
+
+You may also shortcut the `find` method by enclosing a CSS selector in square
+brackets: `page["#my-thing"]`.
 
 These are provided as a convenience so you have several simple and obvious
-options for accessing the content of the page (DOM).
+options for accessing and changing the content of the page.
 
 All the Python objects returned by these attributes and method are instances of
-classes defined in the `pyscript.web.elements` namespace.
+classes relating to HTML elements defined in the `pyscript.web` namespace.
 
-#### `pyscript.web.elements.*`
+#### `pyscript.web.*`
 
 There are many classes in this namespace. Each is a one-to-one mapping of any
 HTML element name to a Python class representing the HTML element of that

docs/user-guide/dom.md

@@ -99,39 +99,45 @@ There are three core concepts to remember:
   The `find` API uses exactly the [same queries](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Locating_DOM_elements_using_selectors)
   as those used by native browser methods like `qurerySelector` or
   `querySelectorAll`.
-* Use classes in the `pyscript.web.elements` namespace to create and organise
+* Use classes in the `pyscript.web` namespace to create and organise
   new elements on the web page.
 * Collections of elements allow you to access and change attributes en-mass.
   Such collections are returned from `find` queries and are also used for the
   [children](https://developer.mozilla.org/en-US/docs/Web/API/Element/children)
   of an element.
 
-You have several options for accessing the content of the page (i.e. the DOM),
-and these can be found in the `pyscript.web.dom` object. The `head` and `body`
-attributes reference the page's head and body. Furthermore, the `find` method
-can be used to return collections of elements matching your CSS query. Finally,
-all elements have a `find` method that searches within their children for
-elements matching your CSS query.
+You have several options for accessing the content of the page, and these are
+all found in the `pyscript.web.page` object. The `html`, `head` and `body`
+attributes reference the page's top-level html, head and body. As a convenience
+the `page`'s `title` attribute can be used to get and set the web page's title
+(usually shown in the browser's tab). The `append` method is a shortcut for
+adding content to the page's `body`. Whereas, the `find` method is used to
+return collections of elements matching a CSS query. You may also shortcut
+`find` via a CSS query in square brackets. Finally, all elements have a `find`
+method that searches within their children for elements matching your CSS
+query.
 
 ```python
-from pyscript.web import dom
+from pyscript.web import page
 
 
 # Print all the child elements of the document's head.
-print(dom.head.children)
+print(page.head.children)
 # Find all the paragraphs in the DOM.
-paragraphs = dom.find("p")
+paragraphs = page.find("p")
+# Or use square brackets.
+paragraphs = page["p"]
 ```
 
 The object returned from a query, or used as a reference to an element's
 children is iterable:
 
 ```python
-from pyscript.web import dom
+from pyscript.web import page
 
 
 # Get all the paragraphs in the DOM.
-paragraphs = dom.find("p")
+paragraphs = page["p"]
 
 # Print the inner html of each paragraph.
 for p in paragraphs:
@@ -141,38 +147,36 @@ for p in paragraphs:
 Alternatively, it is also indexable / sliceable:
 
 ```python
-from pyscript.web import dom
+from pyscript.web import page
 
 
 # Get an ElementCollection of all the paragraphs in the DOM
-paragraphs = dom.find("p")
+paragraphs = page["p"]
 
 # Only the final two paragraphs.
 for p in paragraphs[-2:]:
     print(p.html)
 ```
 
-It also makes available the following read and writable attributes related to
-all contained elements:
+You have access to all the standard attributes related to HTML elements (for
+example, the `innerHTML` or `value`), along with a couple of convenient ways
+to interact with classes and CSS styles:
 
 * `classes` - the list of classes associated with the elements.
-* `innerHTML` - the innerHTML of each element.
 * `style` - a dictionary like object for interacting with CSS style rules.
-* `value` - the `value` attribute associated with each element.
 
 For example, to continue the example above, `paragraphs.innerHTML` will return
 a list of all the values of the `innerHTML` attribute on each contained
 element. Alternatively, set an attribute for all elements contained in the
 collection like this: `paragraphs.style["background-color"] = "blue"`.
 
-It's possible to create new elements to add to the DOM:
+It's possible to create new elements to add to the page:
 
 ```python
-from pyscript.web import dom
-from pyscript.web.elements import *
+from pyscript.web import page, div, select, option, button, span, br 
 
 
-dom.body.append(
+page.append(
     div(
         div("Hello!", classes="a-css-class", id="hello"),
         select(
@@ -206,7 +210,7 @@ dom.body.append(
 ```
 
 This example demonstrates a declaritive way to add elements to the body of the
-DOM. Notice how the first (unnamed) arguments to an element are its children.
+page. Notice how the first (unnamed) arguments to an element are its children.
 The named arguments (such as `id`, `classes` and `style`) refer to attributes
 of the underlying HTML element. If you'd rather be explicit about the children
 of an element, you can always pass in a list of such elements as the named
@@ -216,9 +220,7 @@ Of course, you can achieve similar results in an imperative style of
 programming:
 
 ```python
-from pyscript.web import dom
-from pyscript.web.elements import *
-
+from pyscript.web import page, div, p 
 
 
 my_div = div()
@@ -238,10 +240,10 @@ element references from `pyscript.web`:
 
 ```python
 from pyscript import when
-from pyscript.web import dom
+from pyscript.web import page 
 
 
-btn = dom.find("#my-button")
+btn = page["#my-button"]
 
 
 @when("click", btn)