Skip to content

Commit 65894bd

Browse files
committed
fixup! docs: add missing standards for building components
1 parent 818299a commit 65894bd

File tree

1 file changed

+20
-10
lines changed

1 file changed

+20
-10
lines changed

CODING_STANDARDS.md

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -245,8 +245,11 @@ activateRipple() {
245245
```
246246

247247
##### Selectors
248-
* Component selectors should be lowercase and delimited by hyphens.
249-
* Directive selectors should be camel cased.
248+
* Component selectors should be lowercase and delimited by hyphens. Components should use element
249+
selectors except when the component API uses a native HTML element.
250+
* Directive selectors should be camel cased. Exceptions may be made for directives that act like a
251+
component but would have an empty template, or when the directive is intended to match some
252+
existing attribute.
250253

251254
#### Inheritance
252255

@@ -265,8 +268,8 @@ changed, you can do so in [scripts/check-mdc-tests-config.ts](https://github.com
265268
Remember to leave a comment explaining why the change was necessary.
266269

267270
#### Coercion
268-
When defining public properties that are booleans or numbers, use our coercion API to coerce
269-
`@Input`s into specific types.
271+
Component and directive inputs for boolean and number values must use a setter to coerce values to
272+
the expected type using cdk/coercion.
270273
For example:
271274
```ts
272275
@Input() disabled: boolean;
@@ -278,7 +281,7 @@ private _disabled = false;
278281

279282
static ngAcceptInputType_value: BooleanInput;
280283
```
281-
The above code would allow users to set `disabled` similar to how it can be set on native inputs:
284+
The above code allows users to set `disabled` similar to how it can be set on native inputs:
282285
```html
283286
<component disabled></component>
284287
```
@@ -303,9 +306,9 @@ Implementation
303306

304307
Usage
305308
```html
306-
<yourComponent>
309+
<your-component>
307310
<input>
308-
</yourComponent>
311+
</your-component>
309312
```
310313

311314
**Don't:**
@@ -426,13 +429,20 @@ When it is not super obvious, include a brief description of what a class repres
426429

427430
[ts-mixins]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-mix-in-classes
428431

429-
#### Prefer CSS classes to tag names for styling
432+
#### Prefer CSS classes to tag names and attributes for styling
430433
Targeting tag names can cause conflicts with the MDC version of the component. For this reason, use
431-
css class names defined by us instead of tag names.
434+
CSS class names defined by us instead of tag names. We also prefer classes over attributes for
435+
consistency.
432436
```scss
433437
/** Do: */
434438
.mat-mdc-slider { ... }
435439

436440
/** Don't: */
437441
mdc-slider { ... }
438-
```
442+
443+
/** Do: */
444+
.mat-mdc-slider-input { ... }
445+
446+
/** Don't: */
447+
input[type="button"] { ... }
448+
```

0 commit comments

Comments
 (0)