Updates docs.

ZjsComponent/README.md

@@ -5,6 +5,18 @@ modular, reusable front-end UI components. It allows dynamic loading of
 HTML+JS fragments with local script scoping, simple lifecycle hooks, and
 isolated DOM composition without needing a full framework.
 
+A single component is simply a fragment of valid HTML that s downloaded and
+inserted into the DOM. Scripts in that fragment are scoped to that fragment
+alone. An instance of a **ZjsComponent** is created for that fragment which
+will have specific functions (identified by the component author) created as
+methods on that instance.
+
+To insert a component, which can be a full and rich component containing
+complex sub-DOM and methods on the object, do this:
+```html
+   <zjs-component remote-src=somefile.zjsc> </zjs-component>
+```
+
 A single component is a fragment of valid HTML that contains:
 
 1. Zero or more HTML elements,
@@ -18,7 +30,17 @@ closest **ZjsComponent** ancestor and execute the method on that instance.
 At it's minimal usage, **ZjsComponent** can simply be used for client-side
 includes of HTML. With full leverage of all it's features, **ZjsComponent**
 can be used to create reusable HTML web components in the simplest way
-possible.
+possible while allowing the component developer to:
+
+1. Scope access to DOM elements to only those in the HTML fragment that is
+   loaded.
+2. Scope access to Javascript to only that **ZjsComponent** instance
+   represented by the fragment of HTML.
+
+> **NOTE** Not scoping the CSS is a deliberate decision. CSS within the
+> fragment *is not scoped*, to allow usage of site-wide and global theming by
+> the site author. This dual-cutting sword also means that `<style>` elements
+> within a fragment will interfere with the global CSS scopes.
 
 The example below shows how this can be used within plain HTML to let a
 `button` element call a method on the containing **ZjsComponent** instance.
@@ -55,7 +77,7 @@ All attributes are passed to the fragment script as component attributes.
 </zjs-component>
 ```
 
-> **Note** to ease development, change your editor/IDE settings to treat
+> **Note** To ease development, change your editor/IDE settings to treat
 > `.zjsc` files exactly the same as it does `.html` files. You definitely want
 > this so that your editor/IDE does all the correct syntax highlighting,
 > autocompletion and code-formatting for `.zjsc` files that it does for
@@ -72,7 +94,7 @@ Each remote fragment may contain:
 - The scripts executes in isolation and may export functions to bind to the
   component
 
-Example `hello.zjsc`:
+Example `hello.zjsc` component:
 
 ```html
 <div>
@@ -92,12 +114,11 @@ Example `hello.zjsc`:
    // Normal method; the `this` keyword works here too.
    function updateGreeting() {
       const el = this.querySelector("[name='name-input']");
-      this.name = el.innerText;
+      this.name = el.value;
       // No special reason for deferring the call. I just wanted to
-      // demonstrate that the private methods can be called at any time
+      // demonstrate that the methods can be called at any time
-      // even outside of the stack frame that has the called public
+      // even outside of the current stack frame.
-      // method.
+      setTimeout(() => this.displayGreeting());
-      setTimeout(() => displayGreeting());
    }
 
    // Another method, this one won't be exported.
@@ -106,14 +127,24 @@ Example `hello.zjsc`:
       el.innerText = this.name;
    }
 
-   // All public methods *must* be exported like this. If they are
+   // All public methods *must* be exported like this. If they are not
-   // not exported, they are private to this instance and cannot
+   // exported, they are private to the current invocation of this script
-   // be called from outside of this instance.
+   // element and cannot be called from outside of this current environment.
    exports.onConnected = onConnected;
    exports.updateGreeting = updateGreeting;
+   exports.displayGreeting = displayGreeting;
 </script>
 ```
 
+Example usage of above component:
+
+```
+<zjs-component remote-src=zjsc/hello.zjsc
+               greeting=Hello
+               name=world>
+</zjs-component>
+```
+
 ---
 
 ## 🧠 Lifecycle Hooks
@@ -124,7 +155,7 @@ The following optional functions can be defined in the fragment script:
 - **`onDisconnected()`** called when the component is removed from the DOM
 
 These functions, like all functions defined in the script element within a
-.zjsc` page,  have `this` bound to the `zjs-component` instance.
+`.zjsc` page,  have `this` bound to the `zjs-component` instance.
 
 ---