paper-elements rfc specifications

[gertcuykens]

https://elements.polymer-project.org/elements/paper-header-panel

<paper-header-panel mode="waterfall">
  <div class="paper-header">standard</div>
  <div class="content fit">content fits 100% below the header</div>
</paper-header-panel>

https://elements.polymer-project.org/elements/paper-drawer-panel

<paper-drawer-panel>
  <div drawer> Drawer panel... </div>
  <div main> Main panel... </div>
</paper-drawer-panel>

Who was counting container ships during the attribute and class consistency meeting?

Polymer/polymer#1011 damit!

[abdonrd]

+1

[notwaldorf]

Agreed, it's not really consistent. I think in newer elements we've tried to stick more to the "class" name vs the "attribute" name approach (even though in paper-input i totally messed that up and used an attribute). The problem is that we tried to be consistent with the 0.5 elements, so that porting to 1.0 would be easy. Now it's a bit too late, and changing from attributes to classes would introduce a breaking change and make a lot of people unecessarily have to update their code.

/cc @tjsavage for ideas

[tjsavage]

Our line has typically been this is an element-by-element decision. I agree, we should have generally consistently-applied rules around when we prefer classes vs. attributes - based on many of our examples I might say a rough rule is "use attributes to denote children that are required by the parent" and "use classes to denote a kind of child that is not required by the parent element." Does this seem off-base?

That said, we shouldn't have glaring inconsistencies. I think in many cases we don't necessarily have to make a breaking change - we could update elements such that styles and selectors apply for both the class and the attribute, and update the documentation to only reflect the "right" way of denoting the child, and also document that the old way is deprecated. We may also add in deprecation warnings to polylint. This will be a tradeoff between adding complexity and duplication to elements vs. a smooth API surface.

I think broadly we should try to arc toward greater consistency while we're on ^1.0.0, but make sure if we jump to 2.0.0 we take a hard look at the element's use of class vs. attributes. I don't think we should break elements strictly to change attribute vs. class usage, but definitely deprecate where appropriate and possible and take advantage of any other breaking changes to put in the right usage.

[gertcuykens]

Just focus on 2.0, it's too much energie and code required to implement a deprecate warning solution for 1.0. Upgrading from 1.0 to 2.0 wil be a breeze compared to 0.5 -> 1.0 :D Start by comparing elements and map how much inconsistency we are talking about including styling and naming conventions. I want to see @arthurevans list he was working on a year ago :P Make that list public like a polymer element 2.0 rfc. If I can see that list I know we are on the right track for 2.0 and everybody can make a 2.0 branch based on that element 2.0 rfc. PS let me know when the rfc is online so I can spam my attribute, style en class issues there instead.

[tjsavage]

^ Totally fair request. I think it's a bit soon for a complete 2.0 proposal, but I think it's a good idea to start aggregating proposed 2.0 changes in a public place for comment. I want to avoid as much as possible the risk of such as step coming across as "new thing coming soon, so don't use today's thing," as it would certainly be evolutionary from the 1.0 versions. We'll message loud and clear though when such an rfc is up.

[gertcuykens]

Give it a other name then, polymer rfc without a version. I want to avoid as much as possible the risk of new inconsistent elements being born :) without a proper convention molecules decay quickly and release bad radiation to new developers who are not shielded against polymer radiation :) Remember does things still have to be assembled together and every attribute resembles a different wrench :)

[MeTaNoV]

/sub

[gertcuykens]

Don't let Polymer 2.0 fly under the radar again, if we are going to break things we should really break things. Where is the element design spec we where promised that standardised attribute naming conventions etc? Polymer 2.0 should comme with strict element build naming conventions as promised before even thinking about releasing anything that has a 2.0 in its name. Now is the time to clean everything up and break every single element if necessary! Please create a repository that just contains the naming conventions specifications to start with. Thank you

[notwaldorf]

First, in Polymer 2.0 this won't be an issue anymore, so this naming convention document is moot: in the v1 spec, distribution is done via a named slot (vs a random content selector), so the code would actually (and consistently) look like:

<paper-drawer-panel>
  <div slot="drawer"> Drawer panel... </div>
  <div slot="main"> Main panel... </div>
</paper-drawer-panel>

As for the other breaking changes in 2.0, we're trying to make the 1.0 -> 2.0 transition as smooth as possible (blog post), so that it doesn't take another year for teams to upgrade, like what happened for 0.5. This means that the area for breaking changes is much smaller.

[gertcuykens]

The 'easy' transition is mainly done because a handfull of people is going to be responsible to upgrade thousand of internal google products that uses polymer right now :P All I ask is a specification. Even emoji have rfc specifications. If paper-elements and iron-elements don't want to follow the spec fine, create a new branch called rfc-elements that follow the spec, thanks

[notwaldorf]

As I mentioned in my previous message, the initial concern about class vs name consistency comes from how distribution was done in the v0 spec, with content (that let you distribute anything). v1 uses named slots, so that consistency is no longer a problem (you have to specify the name of the slot to distribute to), so I'm not sure what specification you want.

[gertcuykens]

• raised
• noink
• toggles
• select
• icon
• ...

And the list goes on and on for keywords that are common in every element and currently is the wild wild west with no specification what so ever for third party developers.

[gertcuykens]

Just want to add another example of inconsistency because of lack of specifications

noink -> noInk

https://elements.polymer-project.org/elements/paper-tabs

https://github.com/PolymerElements/paper-tabs/blob/master/paper-tabs.html#L241-L250

The sad part is not that there are inconsistencies but because of corporations not allowing us to fix it. Open Source means breaking and fixing things... allot!