Set define as the top level

gilbert · gilbert · commit 3f7c02ec3b27 · 2016-11-15T10:43:41.000-06:00
diff --git a/README.md b/README.md
@@ -24,10 +24,10 @@ You can take the same ideas (and standards), apply them directly server side, to
 #### Define a component
 
 ```javascript
-var components = require("server-components");
+var customElements = require("server-components");
 
 // Define a new class that extends a native HTML Element
-class NewElement extends components.HTMLElement {
+class NewElement extends customElements.HTMLElement {
     // When the element is created during DOM parsing, you can transform the HTML inside it.
     // This can be configurable too, either by setting attributes or adding HTML content
     // inside it or elsewhere in the page it can interact with. Elements can fire events
@@ -39,21 +39,21 @@ class NewElement extends components.HTMLElement {
 }
 
 // Register the element with an element name
-components.customElements.define("my-new-element", NewElement);
+customElements.define("my-new-element", NewElement);
 ```
 
 For examples of more complex component definitions, take a look at the [example components](https://github.com/pimterry/server-components/blob/master/component-examples.md)
 
 #### Use your components
 
 ```javascript
-var components = require("server-components");
+var customElements = require("server-components");
 
 // Render the HTML, and receive a promise for the resulting HTML string.
 // The result is a promise because elements can render asynchronously, by returning
 // promises from their callbacks. This allows elements to render content from
 // external web services, your database, or anything else you can imagine.
-components.renderPage(`
+customElements.renderPage(`
     <html>
     <head></head>
     <body>
@@ -83,15 +83,15 @@ There aren't many published sharable components to drop in quite yet, as it's st
 
 ### Top-level API
 
-#### `components.HTMLElement`
+#### `customElements.HTMLElement`
 
 Creates a returns a new custom HTML element prototype, extending the HTMLElement prototype.
 
 Note that this does *not* register the element. To do that, call `components.registerElement` with an element name, and options (typically including the prototype returned here as your 'prototype' value).
 
 This is broadly equivalent to `Object.create(HTMLElement.prototype)` in browser land, and exactly equivalent here to `Object.create(components.dom.HTMLElement.prototype)`. You can call that yourself instead if you like, but it's a bit of a mouthful.
 
-#### `components.customElements.define(componentName, Constructor)`
+#### `customElements.define(componentName, Constructor)`
 
 Registers an element, so that it will be used when the given element name is found during parsing.
 
@@ -103,25 +103,25 @@ This returns the constructor for the new element, so you can construct and inser
 
 This is broadly equivalent to `document.registerElement` in browser land.
 
-#### `components.renderPage(html)`
+#### `customElements.renderPage(html)`
 
 Takes an HTML string for a full page, and returns a promise for the HTML string of the rendered result. Server Components parses the HTML, and for each registered element within calls its various callbacks (see the Component API) below as it does so.
 
 Unrecognized elements are left unchanged. When calling custom element callbacks any returned promises are collected, and this call will not return until all these promises have completed. If any promises are rejected, this renderPage call will be rejected too.
 
 To support the full DOM Document API, this method requires that you are rendering a full page (including `<html>`, `<head>` and `<body>` tags). If you don't pass in content wrapped in those tags then they'll be automatically added, ensuring your resulting HTML has a full valid page structure. If that's not what you want, take a look at `renderFragment` below.
 
-#### `components.renderFragment(html)`
+#### `customElements.renderFragment(html)`
 
 Takes an HTML string for part of a page, and returns a promise for the HTML string of the rendered result. Server Components parses the HTML, and for each registered element within calls its various callbacks (see the Component API) below as it does so.
 
 Unrecognized elements are left unchanged. When calling custom element callbacks any returned promises are collected, and this call will not return until all these promises have completed. If any promises are rejected, this renderFragment call will be rejected too.
 
 This method renders the content as a [Document Fragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment), a sub-part of a full document. This means if you there are any `<html>`, `<head>` or `<body>` tags in your input, they'll be stripped, as they're not legal within a fragment of a document. Note that this means the provided `document` object in your components will actually be a `DocumentFragment`, not a true `Document` object (although in most cases you can merrily ignore this). If you want to render a full page, take a look at `renderPage` above.
 
-#### `components.dom`
+#### `customElements.dom`
 
-The DOM object (components.dom) exposes traditional DOM objects (normally globally available in browsers) such as the CustomEvent and various HTMLElement classes, typically use inside your component implementations.
+The DOM object (customElements.dom) exposes traditional DOM objects (normally globally available in browsers) such as the CustomEvent and various HTMLElement classes, typically use inside your component implementations.
 
 This is (very) broadly equivalent to `window` in browser land.
 
diff --git a/component-examples.md b/component-examples.md
@@ -14,14 +14,14 @@ With the web component below, rendering `<my-greeting></my-greeting>` will resul
 `<my-greeting>Hi there</my-greeting>`.
 
 ```javascript
-var components = require("server-components");
+var customElements = require("server-components");
 
-class StaticElement extends components.HTMLElement {
+class StaticElement extends customElements.HTMLElement {
     connectedCallback() {
         this.innerHTML = "Hi there"
     }
 }
-components.customElements.define("my-greeting", StaticElement);
+customElements.define("my-greeting", StaticElement);
 ```
 
 This is very basic, and toy cases like this aren't immediately useful, but this can be helpful for standard
@@ -40,17 +40,17 @@ example is below: a visitor counter. All the rage in the 90s, with web component
 comeback!
 
 ```javascript
-var components = require("server-components");
+var customElements = require("server-components");
 
 var currentCount = 0;
 
-class CounterElement extends components.HTMLElement {
+class CounterElement extends customElements.HTMLElement {
     connectedCallback() {
         currentCount += 1;
         this.innerHTML = "There have been " + currentCount + " visitors.";
     }
 }
-components.customElements.define("visitor-counter", CounterElement);
+customElements.define("visitor-counter", CounterElement);
 ```
 
 After a few visitors, this will render `<visitor-counter></visitor-counter>` into something like
@@ -81,16 +81,16 @@ Components can be parameterized in all sorts of ways. One interesting pattern is
 For example, you might want a component that wraps HTML, parses all the text within, and replaces URL strings with actual links (using the excellent [Linkify library](https://github.com/SoapBox/linkifyjs), but here in a server side DOM, not a real one):
 
 ```javascript
-var components = require("server-components");
+var customElements = require("server-components");
 var linkify = require("linkifyjs/element");
 
-class LinkifyElement extends components.HTMLElement {
+class LinkifyElement extends customElements.HTMLElement {
     connectedCallback() {
         // Delegate the whole thing to a real front-end library!
         linkify(this, { target: () => null, linkClass: "autolinked" }, document);
     }
 }
-components.customElements.define("linkify-urls", LinkifyElement);
+customElements.define("linkify-urls", LinkifyElement);
 ```
 
 With this, we can pass HTML into Server Components that looks like
diff --git a/src/index.js b/src/index.js
@@ -20,6 +20,21 @@ var CustomElementRegistry = require('./registry');
 exports.customElements = CustomElementRegistry.instance();
 exports.HTMLElement = CustomElementRegistry.HTMLElement;
 
+
+/**
+ * Re-export methods for convenience
+ */
+exports.define = function (name, constructor, options) {
+    return CustomElementRegistry.instance().define(name, constructor, options);
+};
+exports.get = function (name) {
+    return CustomElementRegistry.instance().get(name);
+};
+exports.whenDefined = function (name) {
+    return CustomElementRegistry.instance().whenDefined(name);
+};
+
+
 const _upgradedProp = '__$CE_upgraded';
 
 
diff --git a/test/asynchrony-test.js b/test/asynchrony-test.js
@@ -1,15 +1,15 @@
 "use strict";
 var expect = require('chai').expect;
 
-var components = require("../src/index.js");
+var customElements = require("../src/index.js");
 
 describe("An asynchronous element", () => {
     beforeEach(() => {
-        components.customElements.reset();
+        customElements.customElements.reset();
     });
 
     it("blocks rendering until they complete", () => {
-        class SlowElement extends components.HTMLElement {
+        class SlowElement extends customElements.HTMLElement {
             connectedCallback() {
                 return new Promise((resolve, reject) => {
                     setTimeout(() => {
@@ -19,37 +19,37 @@ describe("An asynchronous element", () => {
                 });
             }
         }
-        components.customElements.define("slow-element", SlowElement);
+        customElements.define("slow-element", SlowElement);
 
-        return components.renderFragment("<slow-element></slow-element>").then((output) => {
+        return customElements.renderFragment("<slow-element></slow-element>").then((output) => {
             expect(output).to.equal("<slow-element>loaded!</slow-element>");
         });
     });
 
     it("throw an async error if a component fails to render synchronously", () => {
-        class FailingElement extends components.HTMLElement {
+        class FailingElement extends customElements.HTMLElement {
             connectedCallback() {
                 throw new Error();
             }
         }
-        components.customElements.define("failing-element", FailingElement);
+        customElements.define("failing-element", FailingElement);
 
-        return components.renderFragment(
+        return customElements.renderFragment(
             "<failing-element></failing-element>"
         ).then((output) => {
             throw new Error("Should not successfully render");
         }).catch(() => { /* All good. */ });
     });
 
     it("throw an async error if a component fails to render asynchronously", () => {
-        class FailingElement extends components.HTMLElement {
+        class FailingElement extends customElements.HTMLElement {
             connectedCallback() {
                 return Promise.reject(new Error());
             }
         }
-        components.customElements.define("failing-element", FailingElement);
+        customElements.define("failing-element", FailingElement);
 
-        return components.renderFragment(
+        return customElements.renderFragment(
             "<failing-element></failing-element>"
         ).then((output) => {
             throw new Error("Should not successfully render");
diff --git a/test/basics-test.js b/test/basics-test.js
@@ -1,88 +1,88 @@
 "use strict";
 var expect = require('chai').expect;
 
-var components = require("../src/index.js");
+var customElements = require("../src/index.js");
 
 describe("Basic component functionality", () => {
     it("does nothing with vanilla HTML", () => {
         var input = "<div></div>";
 
-        return components.renderFragment(input).then((output) => {
+        return customElements.renderFragment(input).then((output) => {
             expect(output).to.equal(input);
         });
     });
 
-    it("replaces components with their rendered result", () => {
-        class NewElement extends components.HTMLElement {
+    it("replaces customElements with their rendered result", () => {
+        class NewElement extends customElements.HTMLElement {
             connectedCallback() {
                 this.textContent = "hi there";
             }
         }
-        components.customElements.define("my-element", NewElement);
+        customElements.define("my-element", NewElement);
 
-        return components.renderFragment("<my-element></my-element>").then((output) => {
+        return customElements.renderFragment("<my-element></my-element>").then((output) => {
             expect(output).to.equal("<my-element>hi there</my-element>");
         });
     });
 
     it("can wrap existing content", () => {
-        class PrefixedElement extends components.HTMLElement {
+        class PrefixedElement extends customElements.HTMLElement {
             connectedCallback() {
                 this.innerHTML = "prefix:" + this.innerHTML;
             }
         }
-        components.customElements.define("prefixed-element", PrefixedElement);
+        customElements.define("prefixed-element", PrefixedElement);
 
-        return components.renderFragment(
+        return customElements.renderFragment(
             "<prefixed-element>existing-content</prefixed-element>"
         ).then((output) => expect(output).to.equal(
             "<prefixed-element>prefix:existing-content</prefixed-element>"
         ));
     });
 
     it("allows attribute access", () => {
-        class BadgeElement extends components.HTMLElement {
+        class BadgeElement extends customElements.HTMLElement {
             connectedCallback() {
                 var name = this.getAttribute("name");
                 this.innerHTML = "My name is: <div class='name'>" + name + "</div>";
             }
         }
-        components.customElements.define("name-badge", BadgeElement);
+        customElements.define("name-badge", BadgeElement);
 
-        return components.renderFragment(
+        return customElements.renderFragment(
             '<name-badge name="Tim Perry"></name-badge>'
         ).then((output) => expect(output).to.equal(
             '<name-badge name="Tim Perry">My name is: <div class="name">Tim Perry</div></name-badge>'
         ));
     });
 
     it("can use normal document methods like QuerySelector", () => {
-        class SelfFindingElement extends components.HTMLElement {
+        class SelfFindingElement extends customElements.HTMLElement {
             connectedCallback(document) {
                 var hopefullyThis = document.querySelector("self-finding-element");
                 if (hopefullyThis === this) this.innerHTML = "Found!";
                 else this.innerHTML = "Not found, found " + hopefullyThis;
             }
         }
-        components.customElements.define("self-finding-element", SelfFindingElement);
+        customElements.define("self-finding-element", SelfFindingElement);
 
-        return components.renderFragment(
+        return customElements.renderFragment(
             '<self-finding-element></self-finding-element>'
         ).then((output) => expect(output).to.equal(
             '<self-finding-element>Found!</self-finding-element>'
         ));
     });
 
     it("wraps content in valid page content, if rendering a page", () => {
-        return components.renderPage("<empty-div></empty-div>").then((output) => {
+        return customElements.renderPage("<empty-div></empty-div>").then((output) => {
             expect(output).to.equal(
                 "<html><head></head><body><empty-div></empty-div></body></html>"
             );
         });
     });
 
     it("strips <html>, <head> and <body> tags, if only rendering a fragment", () => {
-        return components.renderFragment("<html><body><empty-div><head></head></empty-div></body></html>").then((output) => {
+        return customElements.renderFragment("<html><body><empty-div><head></head></empty-div></body></html>").then((output) => {
             expect(output).to.equal(
                 "<empty-div></empty-div>"
             );
diff --git a/test/element-validation-test.js b/test/element-validation-test.js
@@ -1,13 +1,13 @@
 "use strict";
 var expect = require('chai').expect;
 
-var components = require("../src/index.js");
+var customElements = require("../src/index.js");
 
 describe("Custom element validation", () => {
     it("requires a non-empty name", () => {
         class InvalidElement {}
         expect(() => {
-            components.customElements.define("", InvalidElement);
+            customElements.define("", InvalidElement);
         }).to.throw(
             /The element name '' is not valid./
         );
@@ -16,7 +16,7 @@ describe("Custom element validation", () => {
     it("requires a hyphen in the element name", () => {
         class InvalidElement {}
         expect(() => {
-            components.customElements.define("invalidname", InvalidElement);
+            customElements.define("invalidname", InvalidElement);
         }).to.throw(
             /The element name 'invalidname' is not valid./
         );
@@ -25,7 +25,7 @@ describe("Custom element validation", () => {
     it("doesn't allow elements to start with a hyphen", () => {
         class InvalidElement {}
         expect(() => {
-            components.customElements.define("-invalid-name", InvalidElement);
+            customElements.define("-invalid-name", InvalidElement);
         }).to.throw(
             /The element name '-invalid-name' is not valid./
         );
@@ -34,7 +34,7 @@ describe("Custom element validation", () => {
     it("requires element names to be lower case", () => {
         class InvalidElement {}
         expect(() => {
-            components.customElements.define("INVALID-NAME", InvalidElement);
+            customElements.define("INVALID-NAME", InvalidElement);
         }).to.throw(
             /The element name 'INVALID-NAME' is not valid./
         );
diff --git a/test/example-components.js b/test/example-components.js
diff --git a/test/multiple-element-interactions-test.js b/test/multiple-element-interactions-test.js
diff --git a/test/programmatic-usage-test.js b/test/programmatic-usage-test.js
