Port of github.com/polymer/polymer.

Port Polymer.js Core, the github.com/polymer/polymer code.

Ports all features except where JS interop is blocking us (declaration/path.js and instance/style.js). In particular, this has:
  //   src/declaration/attributes.js
  //   src/declaration/events.js
  //   src/declaration/polymer-element.js
  //   src/declaration/properties.js
  //   src/declaration/prototype.js
  //   src/declaration/styles.js
  //   src/instance/attributes.js
  //   src/instance/base.js
  //   src/instance/events.js
  //   src/instance/mdv.js
  //   src/instance/properties.js
  //   src/instance/utils.js
  //   src/lib/deserialize.js
  //   src/lib/job.js
  //   src/lib/dom.js -- not needed in Dart
  //   src/lib/lang.js -- not needed in Dart
  //   src/lib/super.js -- not needed in Dart

There's also a big architectural change: polymer-element data is now stored in the PolymerDeclaration class, which is separate from PolymerElement. This allows us to avoid duplicate work on every constructor, and should significantly speed up instance creation.

All code is from the same revision:
https://github.com/Polymer/polymer/blob/4dc481c11505991a7c43228d3797d28f21267779

The remaining unported files are for relatively minor features. "declaration/path.js" is for asset URL resolution, and we might have a Pub-based solution instead. "instance/style.js" has an opt-in, advanced style polyfill. It needs "ShadowCSS.shimPolyfillDirectives", and probably isn't too hard to make work in a follow up change.


Other changes:
* attributeChanged lifecycle method is implemented.
* ObservableAnnotation is public so Polymer's @published can subclass it
* bindProperty renamed to onPropertyChange to avoid conflict with Polymer member of the same name.
* polymer/lib/boot.js preload's polymer-element and link[rel=stylesheet]

R=blois@google.com

Committed: https://code.google.com/p/dart/source/detail?r=28134

[Jennifer Messerly, 2013-09-27 19:14:33]

Hey Pete, I'm still porting more tests, but I think this is ready to start
review if you're up for it.

As usual: I tried to keep the names and style close to the original code. This
makes it a lot easier to apply patches later, because you can grep for the right
method name.

If we find issues we think should be fixed in the original JS code, let's make
sure to get those back to github.com/polymer/polymer. I already sent a couple of
small cleanup pull requests :)

The biggest problem with the original code, IMO, is PolymerElement and
PolymerDeclaration have a *lot* of public API. I think it's probably too much;
some of these methods have subtle invariants such as "should only be called
once". At the very least, they need more documentation so people know what is
safe to call. If we had something like @protected for tooling purposes, it would
go a long way. Let's have a discussion with them on this. For now, the port
attempts to be faithful and keeps all the public APIs public.

As far as porting, it was fairly straightforward:

* Dart doesn't support mixin-of-mixins yet, so I merged all "instance" source
files into src/instance.dart and all "declaration" source files into
src/declaration.dart.

* Instance and declaration share some things that I think are supposed to be
private, so they're now "parts". It lets us play around with the right boundary.

* All APIs named "prototype" are renamed "type". I tried to make these take Type
where possible (Polymer.register), but some need to take ClassMirror because of
a bug that prevents getting the Type from ClassMirror.

* Prototype munging goes away

* JS reflection becomes Dart mirrors

* JS observation uses package: observe

* HTML APIs use dart:html

* For now: we use .xtag and custom_element.dart

* Implement attributeChanged

* The "publish: { foo:1, bar:2 }" idiom becomes @published, which can usually be
used in place of @observable.

* deserializing fields uses the type annotation, not just the initial value.

* registerPolymerElement becomes Polymer.register and takes the Type instead of
a constructor function.

[blois, 2013-09-27 21:40:51]

https://codereview.chromium.org/24149003/diff/42001/pkg/observe/lib/src/bind_...
File pkg/observe/lib/src/bind_property.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/observe/lib/src/bind_...
pkg/observe/lib/src/bind_property.dart:28: void callback()) {
Not related to this change, but I'm curious why this takes a callback and isn't
just a stream of changes.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/boot.js
File pkg/polymer/lib/boot.js (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/boot.js#n...
pkg/polymer/lib/boot.js:79: window.addEventListener('WebComponentsReady',
function() {
WebComponentsReady comes from the CustomElements polyfill, html imports fire
HTMLImportsLoaded.

Is this the right event? How is the custom elements polyfill being loaded?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
File pkg/polymer/lib/deserialize.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
pkg/polymer/lib/deserialize.dart:21: return new DateTime.now();
not the default value?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
pkg/polymer/lib/deserialize.dart:36: var handler =
_typeHandlers[type.qualifiedName];
Is this extensible? What would it take for someone to add a Color deserializer?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/job.dart
File pkg/polymer/lib/job.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/job.dart#...
pkg/polymer/lib/job.dart:47: void complete() {
Any reason complete is public?

If not, can the _timer null check be removed?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/platform....
File pkg/polymer/lib/platform.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/platform....
pkg/polymer/lib/platform.dart:26: new MutationObserver((x, y) {
TODO that this should convert over to dart:async's runAsync? Should have better
timing support in the future.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/decla...
File pkg/polymer/lib/src/declaration.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/decla...
pkg/polymer/lib/src/declaration.dart:240: var registered = type.methods[const
Symbol('registerCallback')];
Out of curiosity, what do they use this for?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
File pkg/polymer/lib/src/instance.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:143: Job job(Job job, void callback(),
Duration wait) =>
Why is this needed?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:151: if (document.window != null ||
alwaysPrepare || _preparingElements > 0) {
Any idea what the scenarios are where these are created in documents which are
not in view? Is this the template?

I'm wondering if we need to delay upgrading of custom elements for a similar
check?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:260: void attributeChanged(String name, String
oldValue) {
FYI- the spec has this as attributeChanged(name, oldValue, newValue), so this
will be changing sometime. Not sure when we should do a BC for it.

I was hoping to get this wired up next week.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:613: new
EventStreamProvider(event).forTarget(node).listen(listener);
how about just node.on[event]

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:800: return new Timer(timeout, method);
Why is the flush performed during invoke and not at callback time? If timeout is
10s, it calls flush immediately?

I see it's what it's like in Polymer, but seems counter-intuitive.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/loade...
File pkg/polymer/lib/src/loader.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/loade...
pkg/polymer/lib/src/loader.dart:47: document.body.dispatchEvent(
Seems like this should be a separate event- when custom element polyfill arrives
this will want to wait for that then raise a new event?

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/prop_att...
File pkg/polymer/test/prop_attr_reflection_test.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/prop_att...
pkg/polymer/test/prop_attr_reflection_test.dart:40:
Platform.endOfMicrotask(expectAsync0(() {
Would be nice to have a Future version of endOfMicrotask, if even only for
tests. These expectAsync0's are always error-prone and I thought there was even
a drive to eliminate them from the test framework.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/take_att...
File pkg/polymer/test/take_attributes_test.html (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/take_att...
pkg/polymer/test/take_attributes_test.html:68: <x-obj id="obj3" values="{
'movie': 'Buckaroo Banzai', 'DOB': '07/31/1978' }"></x-obj>
nit: line lengths

https://codereview.chromium.org/24149003/diff/42001/samples/third_party/todom...
File samples/third_party/todomvc/web/editable_label.dart (right):

https://codereview.chromium.org/24149003/diff/42001/samples/third_party/todom...
samples/third_party/todomvc/web/editable_label.dart:50:
Polymer.register('editable-label', EditableLabel);
Any idea why this uses the explicit register rather than class annotation?

[Jennifer Messerly, 2013-09-30 17:44:37]

thanks Pete! Sounds like we've got a lot to discuss with Polymer team :). I
started a bug to track these issues.

https://codereview.chromium.org/24149003/diff/42001/pkg/observe/lib/src/bind_...
File pkg/observe/lib/src/bind_property.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/observe/lib/src/bind_...
pkg/observe/lib/src/bind_property.dart:28: void callback()) {
On 2013/09/27 21:40:52, blois wrote:
> Not related to this change, but I'm curious why this takes a callback and
isn't
> just a stream of changes.

Great question. This method is just a shorthand for a common pattern. As a
shorthand declarative form, it is better to take a callback. It's in similar
spirit to "test" and "group" in unitttest. If this returned a stream, you'd have
to add ".listen()" negating one of the nice syntax benefits of Dart over
JavaScript (shorthand lambdas).

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/boot.js
File pkg/polymer/lib/boot.js (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/boot.js#n...
pkg/polymer/lib/boot.js:79: window.addEventListener('WebComponentsReady',
function() {
On 2013/09/27 21:40:52, blois wrote:
> WebComponentsReady comes from the CustomElements polyfill, html imports fire
> HTMLImportsLoaded.
> 
> Is this the right event? How is the custom elements polyfill being loaded?

Yes it is right. As TODO notes this code is copy+paste from polymer/src/boot.js

If you look in the custom element polyfill, the order is HTMLImportsLoaded (if
polyfill, otherwise DOMContentLoaded) followed by WebComponentsReady.

This is kinda wrong right now because custom_element.dart is a very limited
xtags polyfill. It will be right after your change lands to switch Polymer to
real custom elements

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
File pkg/polymer/lib/deserialize.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
pkg/polymer/lib/deserialize.dart:21: return new DateTime.now();
On 2013/09/27 21:40:52, blois wrote:
> not the default value?

Yeah, agreed. I filed https://code.google.com/p/dart/issues/detail?id=13666 so
we can collect all of these comments.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/deseriali...
pkg/polymer/lib/deserialize.dart:36: var handler =
_typeHandlers[type.qualifiedName];
On 2013/09/27 21:40:52, blois wrote:
> Is this extensible? What would it take for someone to add a Color
deserializer?

agreed, added to #13666

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/job.dart
File pkg/polymer/lib/job.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/job.dart#...
pkg/polymer/lib/job.dart:47: void complete() {
On 2013/09/27 21:40:52, blois wrote:
> Any reason complete is public?
> 
> If not, can the _timer null check be removed?

See TODO, I had the same question :). But yeah, I added to #13666

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
File pkg/polymer/lib/src/instance.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:143: Job job(Job job, void callback(),
Duration wait) =>
On 2013/09/27 21:40:52, blois wrote:
> Why is this needed?

agreed, this is a good question for Polymer.js guys, added a note to #13666

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:151: if (document.window != null ||
alwaysPrepare || _preparingElements > 0) {
On 2013/09/27 21:40:52, blois wrote:
> Any idea what the scenarios are where these are created in documents which are
> not in view? Is this the template?
> 
> I'm wondering if we need to delay upgrading of custom elements for a similar
> check?

yeah, it's to workaround <template> upgrading elements

IMO, it's a bug in the spec and we should push to get it fixed at that level.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:260: void attributeChanged(String name, String
oldValue) {
On 2013/09/27 21:40:52, blois wrote:
> FYI- the spec has this as attributeChanged(name, oldValue, newValue), so this
> will be changing sometime. Not sure when we should do a BC for it.
> 
> I was hoping to get this wired up next week.

SGTM. I guess Polymer.js will be dealing with this soon too.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:613: new
EventStreamProvider(event).forTarget(node).listen(listener);
On 2013/09/27 21:40:52, blois wrote:
> how about just node.on[event]

Doh, I thought it was deprecated; if it's un-deprecated I'll gladly use it.
Done.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/insta...
pkg/polymer/lib/src/instance.dart:800: return new Timer(timeout, method);
On 2013/09/27 21:40:52, blois wrote:
> Why is the flush performed during invoke and not at callback time? If timeout
is
> 10s, it calls flush immediately?
> 
> I see it's what it's like in Polymer, but seems counter-intuitive.

Agree, added to #13666

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/loade...
File pkg/polymer/lib/src/loader.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/lib/src/loade...
pkg/polymer/lib/src/loader.dart:47: document.body.dispatchEvent(
On 2013/09/27 21:40:52, blois wrote:
> Seems like this should be a separate event- when custom element polyfill
arrives
> this will want to wait for that then raise a new event?

I don't see why we'd need an extra event over polymer.js, unless we messed up
something in the timing. I need it now because I'm still using xtags based
custom_element "polyfill".

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/prop_att...
File pkg/polymer/test/prop_attr_reflection_test.dart (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/prop_att...
pkg/polymer/test/prop_attr_reflection_test.dart:40:
Platform.endOfMicrotask(expectAsync0(() {
On 2013/09/27 21:40:52, blois wrote:
> Would be nice to have a Future version of endOfMicrotask, if even only for
> tests. These expectAsync0's are always error-prone and I thought there was
even
> a drive to eliminate them from the test framework.

good point. I recall starting that refactoring but reverted for some reason I
can't recall. I'll give it another shot.

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/take_att...
File pkg/polymer/test/take_attributes_test.html (right):

https://codereview.chromium.org/24149003/diff/42001/pkg/polymer/test/take_att...
pkg/polymer/test/take_attributes_test.html:68: <x-obj id="obj3" values="{
'movie': 'Buckaroo Banzai', 'DOB': '07/31/1978' }"></x-obj>
On 2013/09/27 21:40:52, blois wrote:
> nit: line lengths

Done.

https://codereview.chromium.org/24149003/diff/42001/samples/third_party/todom...
File samples/third_party/todomvc/web/editable_label.dart (right):

https://codereview.chromium.org/24149003/diff/42001/samples/third_party/todom...
samples/third_party/todomvc/web/editable_label.dart:50:
Polymer.register('editable-label', EditableLabel);
On 2013/09/27 21:40:52, blois wrote:
> Any idea why this uses the explicit register rather than class annotation?

to show off (and test) the alternate form.

[blois, 2013-09-30 19:40:52]

lgtm

[Jennifer Messerly, 2013-10-01 23:46:14]

Committed patchset #14 manually as r28134 (presubmit successful).