Skip to content

Commit 427da70

Browse files
committed
docs: add missing standards for building components
* Naming conventions for the selectors of components & directives * The tests & public APIs for MDC components should mirror the non-MDC version * Public properties should use coercion
1 parent 4a3ca82 commit 427da70

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

CODING_STANDARDS.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,12 +244,54 @@ activateRipple() {
244244
}
245245
```
246246

247+
##### Selectors
248+
* Component selectors should be lowercase and delimited by hyphens.
249+
* Directive selectors should be camel cased.
250+
247251
#### Inheritance
248252

249253
Avoid using inheritance to apply reusable behaviors to multiple components. This limits how many
250254
behaviors can be composed. Instead, [TypeScript mixins][ts-mixins] can be used to compose multiple
251255
common behaviors into a single component.
252256

257+
#### MDC checks
258+
To ensure backwards compatability, we check that tests written for MDC Components include all of
259+
the same tests that the non-MDC version had. Similarly, we check that the public API of MDC
260+
Components match that of the non-MDC version.
261+
262+
In the case where old tests no longer make sense and should be omitted or the public API should be
263+
changed, you can do so in [scripts/check-mdc-tests-config.ts](https://github.com/angular/components/blob/master/scripts/check-mdc-tests-config.ts) and
264+
[scripts/check-mdc-exports-config.ts](https://github.com/angular/components/blob/master/scripts/check-mdc-exports-config.ts).
265+
Remember to leave a comment explaining why the change was necessary.
266+
267+
#### Coercion
268+
When defining public properties, use our coercion API to coerce `@Input`s into specific types.
269+
For example:
270+
```ts
271+
@Input() disabled: boolean;
272+
get disabled(): boolean { return this._disabled; }
273+
set disabled(v: boolean) { this._disabled = coerceBooleanProperty(v); }
274+
private _disabled = false;
275+
276+
...
277+
278+
static ngAcceptInputType_value: BooleanInput;
279+
```
280+
The above code would allow users to set `disabled` similar to how it can be set on native inputs:
281+
```html
282+
<component disabled></component>
283+
```
284+
Even though an empty string is technically what is being provided as the value of `disabled`,
285+
`ngAcceptInputType` allows the mismatched type to be provided and `coerceBooleanProperty`
286+
interprets the given value (an empty string) to the correct type & value, which in this case would
287+
be `true`.
288+
289+
#### Expose native inputs
290+
Native inputs used in components should be exposed to developers through `ng-content`. This allows
291+
developers to interact directly with the input and allows us to avoid providing custom
292+
implementations for all of the input's native behaviors.
293+
294+
253295
### Angular
254296

255297
#### Host bindings
@@ -354,3 +396,13 @@ When it is not super obvious, include a brief description of what a class repres
354396
```
355397

356398
[ts-mixins]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-mix-in-classes
399+
400+
#### Prefer CSS classes to tag names for styling
401+
TODO(wagnermaciel): Ask @jelbourn why we prefer this.
402+
```scss
403+
/** Do: */
404+
.mat-slider { ... }
405+
406+
/** Don't: */
407+
mat-slider { ... }
408+
```

0 commit comments

Comments
 (0)