select docs & examples

Author: mmalerba

guides/creating-a-custom-form-field-control.md

@@ -70,6 +70,7 @@ class MyTelInput {
 ```
 
 ### Providing our component as a MatFormFieldControl
+
 The first step is to provide our new component as an implementation of the `MatFormFieldControl`
 interface that the `<mat-form-field>` knows how to work with. To do this, we will have our class
 implement `MatFormFieldControl`. Since this is a generic interface, we'll need to include a type
@@ -95,12 +96,15 @@ the `MatFormFieldControl` interface, see the
 properties in this guide.) 
 
 ### Implementing the methods and properties of MatFormFieldControl
+
 #### `value`
+
 This property allows someone to set or get the value of our control. Its type should be the same
 type we used for the type parameter when we implemented `MatFormFieldControl`. Since our component 
 already has a value property, we don't need to do anything for this one.
 
 #### `stateChanges`
+
 Because the `<mat-form-field>` uses the `OnPush` change detection strategy, we need to let it know
 when something happens in the form field control that may require the form field to run change
 detection. We do this via the `stateChanges` property. So far the only thing the form field needs to
@@ -122,6 +126,7 @@ ngOnDestroy() {
 ```
 
 #### `id`
+
 This property should return the ID of an element in the component's template that we want the
 `<mat-form-field>` to associate all of its labels and hints with. In this case, we'll use the host
 element and just generate a unique ID for it.
@@ -133,6 +138,7 @@ static nextId = 0;
 ```
 
 #### `placeholder`
+
 This property allows us to tell the `<mat-form-field>` what to use as a placeholder. In this
 example, we'll do the same thing as `matInput` and `<mat-select>` and allow the user to specify it
 via an `@Input()`. Since the value of the placeholder may change over time, we need to make sure to
@@ -152,6 +158,7 @@ private _placeholder: string;
 ```
 
 #### `ngControl`
+
 This property allows the form field control to specify the `@angular/forms` control that is bound to
 this component. Since we haven't set up our component to act as a `ControlValueAccessor`, we'll just
 set this to `null` in our component. In any real component, you would probably want to implement
@@ -170,6 +177,7 @@ constructor(..., @Optional() @Self() public ngControl: NgControl) { ... }
 ```
 
 #### `focused`
+
 This property indicates whether or not the form field control should be considered to be in a
 focused state. When it is in a focused state, the form field is displayed with a solid color
 underline. For the purposes of our component, we want to consider it focused if any of the part
@@ -195,6 +203,7 @@ ngOnDestroy() {
 ```
 
 #### `empty`
+
 This property indicates whether the form field control is empty. For our control, we'll consider it
 empty if all of the parts are empty.
 
@@ -206,6 +215,7 @@ get empty() {
 ```
 
 #### `shouldPlaceholderFloat`
+
 This property is used to indicate whether the placeholder should be in the floating position. We'll
 use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
 Since the placeholder will be overlapping our control when when it's not floating, we should hide
@@ -228,6 +238,7 @@ span {
 ```
 
 #### `required`
+
 This property is used to indicate whether the input is required. `<mat-form-field>` uses this
 information to add a required indicator to the placeholder. Again, we'll want to make sure we run
 change detection if the required state changes.
@@ -245,6 +256,7 @@ private _required = false;
 ```
 
 #### `disabled`
+
 This property tells the form field when it should be in the disabled state. In addition to reporting
 the right state to the form field, we need to set the disabled state on the individual inputs that
 make up our component.
@@ -269,6 +281,7 @@ private _disabled = false;
 ```
 
 #### `errorState`
+
 This property indicates whether the associated `NgControl` is in an error state. Since we're not
 using an `NgControl` in this example, we don't need to do anything other than just set it to `false`.
 
@@ -277,6 +290,7 @@ errorState = false;
 ```
 
 #### `controlType`
+
 This property allows us to specify a unique string for the type of control in form field. The
 `<mat-form-field>` will add an additional class based on this type that can be used to easily apply
 special styles to a `<mat-form-field>` that contains a specific type of control. In this example
@@ -288,6 +302,7 @@ controlType = 'my-tel-input';
 ```
 
 #### `setAriaDescribedByIds(ids: string[])`
+
 This method is used by the `<mat-form-field>` to specify the IDs that should be used for the
 `aria-describedby` attribute of your component. The method has one parameter, the list of IDs, we
 just need to apply the given IDs to our host element.
@@ -301,6 +316,7 @@ setDescribedByIds(ids: string[]) {
 ```
 
 #### `onContainerClick(event: MouseEvent)`
+
 This method will be called when the form field is clicked on. It allows your component to hook in
 and handle that click however it wants. The method has one parameter, the `MouseEvent` for the
 click. In our case we'll just focus the first `<input>` if the user isn't about to click an
@@ -315,6 +331,7 @@ onContainerClick(event: MouseEvent) {
 ```
 
 ### Trying it out
+
 Now that we've fully implemented the interface, we're ready to try our component out! All we need to
 do is place it inside of a `<mat-form-field>`
 

src/lib/form-field/form-field.md

@@ -14,6 +14,7 @@ The following Angular Material components are designed to work inside a `<mat-fo
 <!-- example(form-field-overview) -->
 
 ### Floating placeholder
+
 The floating placeholder is a text label displayed on top of the form field control when
 the control does not contain any text. By default, when text is present the floating placeholder
 floats above the form field control.
@@ -46,6 +47,7 @@ setting can be either `always`, `never`, or `auto`.
 ```
 
 ### Hint labels
+
 Hint labels are additional descriptive text that appears below the form field's underline. A
 `<mat-form-field>` can have up to two hint labels; one start-aligned (left in an LTR language, right
 in RTL), and one end-aligned.
@@ -60,6 +62,7 @@ raise an error.
 <!-- example(form-field-hint) -->
 
 ### Error messages
+
 Error messages can be shown under the form field underline by adding `mat-error` elements inside the
 form field. Errors are hidden initially and will be displayed on invalid form fields after the user
 has interacted with the element or the parent form has been submitted. Since the errors occupy the
@@ -74,6 +77,7 @@ multiple errors is up to the user.
 <!-- example(form-field-error) -->
 
 ### Prefix & suffix
+
 Custom content can be included before and after the input tag, as a prefix or suffix. It will be
 included within the visual container that wraps the form control as per the Material specification.
 
@@ -83,12 +87,14 @@ the prefix. Similarly, adding `matSuffix` will designate it as the suffix.
 <!-- example(form-field-prefix-suffix) -->
 
 ### Custom form field controls
+
 In addition to the form field controls that Angular Material provides, it is possible to create
 custom form field controls that work with `<mat-form-field>` in the same way. For additional
 information on this see the guide on
 [Creating Custom mat-form-field Controls](https://material.angular.io/guide/creating-a-custom-form-field-control).
 
 ### Theming
+
 `<mat-form-field>` has a `color` property which can be set to `primary`, `accent`, or `warn`. This
 will set the color of the form field underline and floating placeholder based on the theme colors
 of your app.
@@ -105,6 +111,7 @@ mat-form-field.mat-form-field {
 <!-- example(form-field-theming) -->
 
 ### Accessibility
+
 If a floating placeholder is specified, it will be automatically used as the label for the form
 field control. If no floating placeholder is specified, the user should label the form field control
 themselves using `aria-label`, `aria-labelledby` or `<label for=...>`.
@@ -113,16 +120,20 @@ Any errors and hints added to the form field are automatically added to the form
 `aria-describedby` set.
 
 ### Troubleshooting
+
 #### Error: Placeholder attribute and child element were both specified
+
 This error occurs when you have specified two conflicting placeholders. Make sure that you haven't
 included both a `placeholder` property on your form field control and a `<mat-placeholder>`
 element.
 
 #### Error: A hint was already declared for align="..."
+
 This error occurs if you have added multiple hints for the same side. Keep in mind that the
 `hintLabel` property adds a hint to the start side.
 
 #### Error: mat-form-field must contain a MatFormFieldControl
+
 This error occurs when you have not added a form field control to your form field. If your form
 field contains a native `<input>` or `<textarea>` element, make sure you've added the `matInput`
 directive to it. Other components that can act as a form field control include `<mat-select>`,

src/lib/input/input.md

@@ -4,6 +4,7 @@
 <!-- example(input-overview) -->
 
 ### `<input>` and `<textarea>` attributes
+
 All of the attributes that can be used with normal `<input>` and `<textarea>` elements can be used
 on elements inside `<mat-form-field>` as well. This includes Angular directives such as `ngModel`
 and `formControl`.
@@ -13,6 +14,7 @@ The only limitations are that the `type` attribute can only be one of the values
 also contains an `<mat-placeholder>` element.
 
 ### Supported `<input>` types
+
 The following [input types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) can
 be used with `matInput`:
 * date
@@ -29,20 +31,23 @@ be used with `matInput`:
 * week
 
 ### Form field features
+
 There are a number of `<mat-form-field>` features that can be used with any `<input matInput>` or
 `<textarea matInput>`. These include error messages, hint text, prefix & suffix, and theming. For
 additional information about these features, see the
 [form field documentation](https://material.angular.io/components/form-field/overview).
 
 ### Placeholder
+
 A placeholder is a text label displayed in the input area when the input does not contain text.
-When text is present, placeholder will float above the input area. The placeholder can be specified
-either via a `placeholder` attribute on the input or a `<mat-placeholder>` element in the same
-form field at the `matInput`. The `<mat-form-field>` also has additional options for changing the
-behavior of the placeholder. For more information see the
+When text is present, the placeholder will float above the input area. The placeholder can be
+specified either via a `placeholder` attribute on the input or a `<mat-placeholder>` element in the
+same form field as the `matInput`. The `<mat-form-field>` also has additional options for changing
+the behavior of the placeholder. For more information see the
 [form field placeholder documentation](https://material.angular.io/components/form-field/overview#floating-placeholder).
 
-### Custom Error Matcher
+### Changing when error messages are shown
+
 The `<mat-form-field>` allows you to
 [associate error messages](https://material.angular.io/components/form-field/overview#error-messages)
 with your `matInput`. By default, these error messages are shown when the control is invalid and
@@ -56,23 +61,6 @@ indicating that they should be shown, and `false` indicating that they should no
 
 <!-- example(input-error-state-matcher-example) -->
 
-```html
-<mat-form-field>
-  <input matInput [(ngModel)]="myInput" required [errorStateMatcher]="myErrorStateMatcher">
-  <mat-error>This field is required</mat-error>
-</mat-form-field>
-```
-
-```ts
-class MyErrorStateMatcher implements ErrorStateMatcher {
-  isErrorState(control: FormControl | null, form: FormGroupDirective | NgForm | null): boolean {
-    // Error when invalid control is dirty, touched, or submitted
-    const isSubmitted = form && form.submitted;
-    return !!(control && control.invalid && (control.dirty || control.touched || isSubmitted)));
-  }
-}
-```
-
 A global error state matcher can be specified by setting the `ErrorStateMatcher` provider. This
 applies to all inputs. For convenience, `ShowOnDirtyErrorStateMatcher` is available in order to
 globally cause input errors to show when the input is dirty and invalid.
@@ -86,6 +74,7 @@ globally cause input errors to show when the input is dirty and invalid.
 ```
 
 ### Auto-resizing `<textarea>` elements
+
 `<textarea>` elements can be made to automatically resize to fit their contents by applying the
 `matTextareaAutosize` directive. This works with `<textarea matInput>` elements as well as plain
 native `<textarea>` elements. The min and max size of the textarea can be specified in rows, using
@@ -94,6 +83,7 @@ the `matAutosizeMinRows` and `matAutosizeMaxRows` properties respectively.
 <!-- example(input-autosize-textarea-example) -->
 
 ### Accessibility
+
 The `matInput` directive works with native `<input>` to provide an accessible experience.
 
 If a placeholder attribute is added to the input, or a `mat-placeholder` element is added
@@ -105,7 +95,9 @@ Any `mat-error` and `mat-hint` are automatically added to the input's `aria-desc
 `aria-invalid` is automatically updated based on the input's validity state.
 
 ### Troubleshooting
-#### Error: Input type "..." isn't supported by matInput.
+
+#### Error: Input type "..." isn't supported by matInput
+
 This error is thrown when you attempt to set an input's `type` property to a value that isn't
 supported by the `matInput` directive. If you need to use an unsupported input type with
 `<mat-form-field>` consider writing a