Components: Document why some attribute directive are dash-case and some are camelCase

[thekalinga]

Bug, feature request, or proposal:

Currently there is a confusion as to why mdInput is an attribute directive [which is the reason why it is written as mdInput instead of md-input] & md-button is a component

Since md-button(and other button variants) are used only as html attributes, it would be easy for the user's mental model if he can write

<button mdButton> instead of <button md-button> similar to <input mdInput>

What is the expected behavior?

Ability to use button variations using camelCase such as <button mdButton>

What is the current behavior?

All button variations needs to be used using kabab cased attribute <button md-button>

What is the use-case or motivation for changing an existing behavior?

Now the user needs to know how button is implemented (which is why it is kabab case instead of camel), instead end user should not care how it is implemented, instead just knows elements follow kabab case & directives follow camelCase.

This way, the implementation detail does not leak to end user

The mental model of "html element => component", "html attribute => directive" is easy to remember & intuitive for most angular developers.

Which versions of Angular, Material, OS, browsers are affected?

2.0.0-beta.2

[PowerKiKi]

As a new user of material (but familiar with Angular 1 and Material 1) this difference is hard to understand at first glance. And it looks like material naming is incoherent since both mdInput and md-button are used in the same way, as attributes, but are cased differently. So at first I'd like them to be renamed too.

However renaming them would go directly against the official style guide about custom prefix for components and attribute directives. Not sure what the best of course of action would be...

[michael-lang]

+1 to migrate to mdButton for consistency.

[bradyshutt]

Does the latest release (2.0.0-beta.10) fix this issue?
The first item under Deprecations says:

All dash-case @ Directive selectors are deprecated in favor of the camelCase equivalent. The
dash-case selectors will be removed in a subsequent release. Some examples include:

md-line ---------------> mdLine
md-tab-link ----------> mdTabLink
md-tab-label --------> mdTabLabel
md-card-avatar ----> mdCardAvatar

[jelbourn]

The current behavior is that @Components are dash-case and @Directives are camelCase. The reasoning is that an element can only have _one_ @Component, but multiple @Directive instances. So you can tell by looking at <button mat-button matTooltip="Hello"> that MatButton is the @Component, and all of the unprefixed attributes (disabled, color, disableRipple, etc.) apply to that, while MatTooltip is a directive and its properties would all be prefixed with matTooltip

[thw0rted]

Just came from #18606. I think confusion arose there because the docs agree with @jelbourn, telling you to use camelCase directives, but the example for the same components shows the directives in dash-case (<mat-icon mat-list-icon>folder</mat-icon>).

Would it make sense to resolve this issue by reviewing the docs to ensure that both the Overview and Example tabs of each component consistently use these case conventions?

[jelbourn]

Yes, a docs review would be useful to make sure we're not using any deprecated selectors (we didn't have this rule totally internalized when we first started, and some of the old inconsistent APIs stuck around).