Polymer 2.0 breaking changes

[rictic]

polymer-upgrade's first project is to be a helpful companion when upgrading from Polymer v1 to Polymer v2. For every breaking change listed in the readme we should either automatically transform to the correct new code or provide a warning with an explanation of what needs to change and provide more info.

This issue will act as a tracking bug for tools support for handling those changes needed to convert from a Polymer v1 element to a hybrid Polymer v1 & v2 element.

The gold standard fix is an automatic and transformation of code here in polymer-upgrade. Next best is a lint warning or error. The remaining changes will need to be documented particularly visibly and thoroughly.

Polymer.dom

• [ ] Polymer.dom will no longer return Arrays for API's where the platform returns e.g. NodeList's, so code may need to be updated to avoid direct use of array methods.

  V1 Shadow DOM

  Distribution

• [ ] <content> insertion points must be changed to <slot>
• [ ] Insertion points that selected content via <content select="..."> must be changed to named slots: <slot name="...">
• [ ] Selection of distributed content into named slots must use slot="..." rather than tag/class/attributes selected by <content>
• [ ] Re-distributing content by placing a <slot> into an element that itself has named slots requires placing a name attribute on the <slot> to indicate what content it selects from its host children, and placing a slot attribute to indicate where its selected content should be slotted into its parent
• [ ] In the V1 "Shady DOM" shim, initial distribution of children into <slot> is asynchronous (microtask) to creating the shadowRoot, meaning distribution occurs after observers/ready (in Polymer 1.0's shim, initial distribution occurred before ready). In order to force distribution synchronously, call ShadyDOM.flush().

  Scoped styling

• [ ] ::content CSS pseudo-selectors must be changed to ::slotted
  • [ ] they may only target immediate children and use no descendant selectors
• [ ] :host-context() pseudo-selectors have been removed. These were primarily useful for writing bidi rules (e.g. :host-context([dir=rtl])); these should be replaced with the new :dir(rtl) selector, which we plan to polyfill in the styling shim soon
• [ ] The previously deprecated /deep/ and ::shadow selectors have been completely removed from V1 native support and must not be used (use CSS custom properties to customize styling instead)

  Scoped events

• [ ] Code using Polymer.dom(event).localTarget should change to the V1 standard API event.target
• [ ] Code using Polymer.dom(event).path (aka V0 event.path) should change to the V1 standard API event.composedPath()
• [ ] Code using Polymer.dom(event).rootTarget (aka V0 event.path[0]) should change to the V1 standard API event.composedPath()[0]

  V1 Custom Elements

• [ ] The V1 Custom Elements spec forbids reading attributes, children, or parent information from the DOM API in the constructor (or created when using the legacy API). Likewise, attributes and children may not be added in the constructor. Any such work must be deferred (e.g. until connectedCallback or microtask/setTimeout/requestAnimationFrame).
• [ ] Polymer will no longer produce type-extension elements (aka is="..."). Although they are still included in the V1 Custom Elements spec and scheduled for implementation in Chrome, because Apple has stated it will not implement is, we will not be encouraging its use to avoid indefinite reliance on the Custom Elements polyfill. Instead, a wrapper custom element can surround a native element, e.g. <a is="my-anchor">...</a> could become <my-anchor><a>...</a></my-anchor>. Users will need to change existing is elements where necessary.

• [ ] All template type extensions provided by Polymer have now been changed to standard custom elements that take a <template> in their light dom, e.g.

  <template is="dom-repeat" items="{{items}}">...</template>

  should change to

  <dom-repeat items="{{items}}">
    <template>...</template>
  </dom-repeat>

  • [ ] For the time being, Polymer() will automatically wrap template extensions used in Polymer element templates during template processing for backward-compatibility, although we may decide to remove this auto-wrapping in the future.
  • [ ] Templates used in the main document must be manually wrapped.

• [x] The custom-style element has also been changed to a standard custom element that must wrap a style element e.g.

  <style is="custom-style">...</style>

  should change to

  <custom-style>
  <style>...</style>
  </custom-style>

  • Automatic fix: https://github.com/Polymer/polymer-upgrade/pull/5

    CSS Custom Property Shim

• [ ] The shim will now always use native CSS Custom Properties by default on browsers that implement them (this was opt-in in 1.0). The shim will perform a one-time transformation of stylesheets containing CSS Custom Property mixins to leverage individual native CSS properties where possible for better performance. This introduces some limitations to be aware of.
• [ ] :root {}
  • Should be :host > * {} (in a shadow root)
  • Should be html {} (in main document)
  • Thus, cannot share old :root styles for use in both main document and shadow root
• [x] var(--a, --b)
  • Should be var(--a, var(--b))
  • Automatical fix: https://github.com/Polymer/polymer-upgrade/pull/2
• [x] @apply(--foo)
  • Should be @apply --foo;
  • Automatic fix: https://github.com/Polymer/polymer-upgrade/pull/3
• [ ] element.customStyle as an object that can be assigned to has been removed; use element.updateStyles({...}) instead.
• [x] <style> inside of a <dom-module>, but outside of <template> is no longer supported
  • Automatic fix: https://github.com/Polymer/polymer-upgrade/pull/2
• [ ] Imperatively created custom-styles (e.g. document.createElement('style', 'custom-style')) are no longer supported.

  Data system

• [ ] An element's template is not stamped & data system not initialized (observers, bindings, etc.) until the element has been connected to the main document. This is a direct result of the V1 changes that prevent reading attributes in the constructor.
• [ ] Re-setting an object or array no longer dirty checks, meaning you can make deep changes to an object/array and just re-set it, without needing to use set/notifyPath. Although the set API remains and will often be the more efficient way to make changes, this change removes users of Polymer elements from needing to use this API, making it more compatible with alternate data-binding and state management libraries.
• [ ] Propagation of data through the binding system is now batched, such that multi-property computing functions and observers run once with a set of coherent changes. Single property accessors still propagate data synchronously, although there is a new setProperties({...}) API on Polymer elements that can be used to propagate multiple values as a coherent set.
• [ ] Multi-property observers and computed methods are now called once at initialization if any arguments are defined (and will see undefined for any undefined arguments)
• [ ] Inline computed annotations run once unconditionally at initialization, regardless if any arguments are defined (and will see undefined for undefined arguments)
• [ ] Setting/changing any function used in inline template annotations will cause the binding to re-compute its value using the new function and current property values ‘notify’ events not fired when value changes as result of binding from host
• [ ] In order for a property to be deserialized from its attribute, it must be declared in the properties metadata object
• [ ] The Polymer.Collection and associated key-based path and splice notification for arrays has been eliminated. See explanation here for more details.

  Removed API

• [ ] Polymer.instanceof and Polymer.isInstance: no longer needed, use instanceof and instanceof Polymer.Element instead.
• [x] dom-module: Removed ability to use is and name attribute to configure the module name. The only supported declarative way set the module id is to use id.
  • Automatic fix: https://github.com/Polymer/polymer-upgrade/pull/6
• [ ] element.getPropertyInfo: This api returned unexpected information some of the time and was rarely used.
• [ ] element.getNativePrototype: Removed because it is no longer needed for internal code and was unused by users.
• [ ] element.beforeRegister: This was originally added for metadata compatibility with ES6 classes. We now prefer users create ES6 classes by extending Polymer.Element, specifying metadata in the static config property. For legacy use via Polymer({...}), dynamic effects may now be added using the registered lifecycle method.
• [ ] element.attributeFollows: Removed due to disuse.
• [ ] element.classFollows: Removed due to disuse.
• [ ] listeners: Removed ability to use id.event to add listeners to elements in local dom. Use declarative template event handlers instead.
• [ ] Methods starting with _ are not guaranteed to exist (most have been removed)

  Other

• [ ] Attached: no longer deferred until first render time. Instead when measurement is needed use... API TBD.
• [ ] The legacy created callback is no longer called before default values in properties have been set. As such, you should not rely on properties set in created from within value functions that define property defaults. However, you can now set any property defaults within the created callback (in 1.0 this was forbidden for observed properties) in lieu of using the value function in properties.
• [ ] Binding a default value of false via an attribute binding to a boolean property will not override a default true property of the target, due to the semantics of boolean attributes. In general, property binding should always be used when possible, and will avoid such situations.
  • [ ] lazyRegister option removed and all meta-programming (parsing template, creating accessors on prototype, etc.) is deferred until the first instance of the element is created
  • [ ] Polymer 2.0 uses ES2015 syntax, and can be run without transpilation in current Chrome, Safari 10, Safari Technology Preview, Firefox, and Edge. Transpilation is required to run in IE11 and Safari 9. We will be releasing tooling for development and production time to support this need in the future.

    Not yet implemented

• [ ] <array-selector> not yet implemented
• [ ] Polymer.dom: currently most of this is emulated, but some api's may be missing. Please file issues to determine if the missing behavior is an intended breaking change.

[cordovapolymer]

@rictic Is the polymer-upgrade tool usable? I'd like to upgrade my project for use with polymer 2.0.0-rc2

[rictic]

In the process of developing the upgrader we realized that it had a ton of overlap with the new linter (registry, configuration, etc). So the plan is to be able to run polymer lint to discover any issues your code has with your chosen version of Polymer (1.0, 2.0, 2.0-hybrid), and to be able to run polymer lint --fix to automatically fix as many of those issues as have unambiguous fixes.

You can try out the new linter by running polymer experimental-lint in polymer-cli@next, and in the next couple of weeks it will replace the old linter, and run as polymer lint.

[rictic]

polymer lint --fix is now implemented in the polymer-cli at master and will be in the next major release.

[skyred]

It looks polymer lint --fix was included in the polymer-cli v1.5.7 https://github.com/Polymer/polymer-cli/compare/v1.5.7...master

I gave it a try, resulting a broken site. I noticed the problems were related to this.$.* local selectors used by NeonAnimation. I am not sure if there exists an easy fix?

The site is hosted on https://github.com/techyizu/techyizu.github.io, the attempt of the upgrade is at branch https://github.com/techyizu/techyizu.github.io/commit/8bbf3367b3d6ff295198e6c3ad1551ec1ec8fd4e

@rictic Can you point me to which change on https://www.polymer-project.org/2.0/docs/upgrade that I need to fix manually?

[rictic]

@skyred Please file a new bug with more information about what specific problems you're seeing at https://github.com/Polymer/polymer-linter