Implement custom element construction and some 'define' checks

third_party/WebKit/Source/core/dom/custom/README.md

Index: third_party/WebKit/Source/core/dom/custom/README.md
diff --git a/third_party/WebKit/Source/core/dom/custom/README.md b/third_party/WebKit/Source/core/dom/custom/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ac4fa41f9c9627675efb3c3ac0558a607add5a10
--- /dev/null
+++ b/third_party/WebKit/Source/core/dom/custom/README.md
@@ -0,0 +1,144 @@
+# Custom Elements
+
+Custom elements let authors create their own elements, with their own
+methods, behavior, and attribute handling. Custom elements shipped in
+M33. We colloquially refer to that version as "v0."
+
+Contact Dominic Cooney
+([dominicc@chromium.org](mailto:dominicc@chromium.org)) with
+questions.
+
+## Design
+
+### Some Important Classes
+
+###### CustomElementDefinition
+
+The definition of one ‘class’ of element; it consists of a
+tag name, and a prototype.
+
+###### CustomElementsRegistry
+
+Implements the `window.customElements` property. This maintains a list
+of definitions, and a mapping from constructors to an index in this
+list. The map is necessary for finding a custom element definition
+given only a constructor.
+
+###### V8HTMLElement Constructor
+
+The `HTMLElement` interface constructor. When a custom element is
+created from JavaScript all we have to go on is the constructor (in
+`new.target`); this uses CustomElementRegistry’s map to find
+which definition to use.
+
+### Memory Management
+
+Once defined, custom element constructors and prototypes have to be
+kept around indefinitely because they could be created in future by
+the parser. On the other hand, we must not leak when a window can no
+longer run script.
+
+The principle we follow is to only have C++ objects have weak
+references to JavaScript objects, and have the wrapper objects keep
+the JavaScript objects alive. Specifically, the CustomElementsRegistry
+wrapper implements visitDOMWrapper to keep its constructor map alive;
+this in turn references the constructor (via the map key) and the
+prototype (via the constructor’s prototype property) in
+JavaScript.
+
+## Style Guide
+
+In comments and prose, write custom elements, not Custom Elements, to
+match the HTML standard.
+
+Prefix type names with CustomElement (singular). The one exception to
+this rule is CustomElementsRegistry, which uses a plural to match the
+name of the interface in the specification.
+
+## Testing
+
+Custom elements have small C++ unit tests and medium
+“layout” tests.
+
+###### C++ Unit Tests
+
+These are in third_party/WebKit/Source/core/dom/*Test.cpp and are
+built as part of the webkit_unit_tests target. The test names start
+with CustomElement so you can run them with:
+
+    $ out/Debug/webkit_unit_tests --gtest_filter=CustomElement*
+
+###### Layout Tests
+
+The custom element layout tests are generally in
+third_party/WebKit/LayoutTests/custom-elements.
+
+All custom elements layout tests use the [W3C web-platform-tests
+harness](http://testthewebforward.org/docs/) and follow its style. The
+W3C is not very prescriptive, so be consistent with other custom
+elements tests.
+
+When naming tests, use short names describing what the test is doing.
+Avoid articles. For example, "HTMLElement constructor, invoke". When
+writing assertion messages, start with a lowercase letter (unless the
+word is a proper noun), use normal grammar and articles, and include
+the word “should” to leave no doubt whate the expected
+behavior is.
+
+###### Spec Tests
+
+These will be upstreamed to the W3C, replacing [the tests for
+registerElement](https://github.com/w3c/web-platform-tests/commits/master/custom-elements)
+we contributed earlier. To facilitate that, follow these guidelines:
+
+* Keep the tests together in the `spec` directory.
+* Only test things required in a spec. The test should permit other
+  possible reasonable implementations.
+* Avoid using Blink-specific test mechanisms. Don't use
+  `window.internals` for example.
+
+###### Implementation Tests
+
+These are for testing Blink-specific details like object lifetimes,
+crash regressions, interaction with registerElement and HTML Imports,
+and so on.
+
+These tests can use Blink-specific testing hooks like
+`window.internals` and `testRunner`.
+
+###### Web Exposed Tests
+
+Finally there are /TODO(dominicc): should be/ tests in
+webexposed/custom-elements which assert that we HAVE NOT shipped
+`window.customElements.define` yet. These tests need to be updated
+when we ship `window.customElements.define` or remove
+`registerElement`.
+
+## “V0” Deprecation
+
+The plan is to:
+
+1. Implement the ‘new’ kind of custom elements separately
+   from the existing implementation. We have renamed all of old
+   implementation so that the type names start with V0; it should be
+   easy to tell whether you are looking at the old or new
+   implementation.
+1. When we ship `window.customElements.define`, add a deprecation
+   warning to `document.registerElement` directing authors to use the
+   new API.
+1. Change the ‘web’ API to use the new kind of custom
+   elements. That API is used by extensions to implement the webview
+   tag and things like that.
+1. When [the use counter for
+   registerElement](https://www.chromestatus.com/metrics/feature/timeline/popularity/457)
+   drops below 0.03% of page loads, remove the old implementation. We
+   may remove it even sooner, if we have evidence that sites are using
+   feature detection correctly.
+
+## References
+
+These have links to the parts of the DOM and HTML specs which define
+custom elements:
+
+* [WHATWG DOM Wiki: Custom Elements](https://github.com/whatwg/dom/wiki#custom-elements)
+* [WHATWG HTML Wiki: Custom Elements](https://github.com/whatwg/html/wiki#custom-elements)