Skip to content

Commit 9db31ee

Browse files
SplaktarSplaktar
authored
docs: create anchors for all header elems & fix a11y in guides (#21751)
- Lighthouse's a11y audit wants page headers to progress in order - https://web.dev/heading-order/ - Go through all guides and make the headers consistent - and ordered to pass the a11y audit - fix grammar issues and typos
1 parent ab8f62f commit 9db31ee

14 files changed

+256
-227
lines changed

‎guides/bidirectionality.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
# Angular Material bi-directionality
22

3-
### Setting a text-direction for your application
3+
## Setting a text-direction for your application
4+
45
The [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
56
is typically applied to `<html>` or `<body>` element of a page. However, it can be used on any
67
element, within your Angular app, to apply a text-direction to a smaller subset of the page.
78

89
All Angular Material components automatically reflect the LTR/RTL direction
910
of their container.
1011

11-
### Reading the text-direction in your own components
12+
## Reading the text-direction in your own components
13+
1214
`@angular/cdk/bidi` provides a `Directionality` injectable that can be used by any component
1315
in your application. To consume it, you must import `BidiModule` from `@angular/cdk/bidi`.
1416

@@ -18,7 +20,8 @@ in your application. To consume it, you must import `BidiModule` from `@angular/
1820
captures changes from `dir` attributes _inside the Angular application context_. It will not
1921
emit for changes to `dir` on `<html>` and `<body>`, as they are assumed to be static.
2022

21-
#### Example
23+
### Example
24+
2225
```ts
2326
@Component({ /* ... */ })
2427
export class MyCustomComponent {

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ export class MyTelInput {
7272
}
7373
```
7474

75-
### Providing our component as a MatFormFieldControl
75+
## Providing our component as a MatFormFieldControl
7676

7777
The first step is to provide our new component as an implementation of the `MatFormFieldControl`
7878
interface that the `<mat-form-field>` knows how to work with. To do this, we will have our class
@@ -91,7 +91,7 @@ export class MyTelInput implements MatFormFieldControl<MyTel> {
9191
}
9292
```
9393

94-
This sets up our component so it can work with `<mat-form-field>`, but now we need to implement the
94+
This sets up our component, so it can work with `<mat-form-field>`, but now we need to implement the
9595
various methods and properties declared by the interface we just implemented. To learn more about
9696
the `MatFormFieldControl` interface, see the
9797
[form field API documentation](https://material.angular.io/components/form-field/api).
@@ -185,7 +185,7 @@ constructor(
185185

186186
Note that if your component implements `ControlValueAccessor`, it may already be set up to provide
187187
`NG_VALUE_ACCESSOR` (in the `providers` part of the component's decorator, or possibly in a module
188-
declaration). If so you may get a *cannot instantiate cyclic dependency* error.
188+
declaration). If so, you may get a *cannot instantiate cyclic dependency* error.
189189

190190
To resolve this, remove the `NG_VALUE_ACCESSOR` provider and instead set the value accessor directly:
191191

@@ -224,7 +224,7 @@ For additional information about `ControlValueAccessor` see the [API docs](https
224224

225225
#### `focused`
226226

227-
This property indicates whether or not the form field control should be considered to be in a
227+
This property indicates whether the form field control should be considered to be in a
228228
focused state. When it is in a focused state, the form field is displayed with a solid color
229229
underline. For the purposes of our component, we want to consider it focused if any of the part
230230
inputs are focused. We can use the `FocusMonitor` from `@angular/cdk` to easily check this. We also
@@ -250,7 +250,7 @@ ngOnDestroy() {
250250
#### `empty`
251251

252252
This property indicates whether the form field control is empty. For our control, we'll consider it
253-
empty if all of the parts are empty.
253+
empty if all the parts are empty.
254254

255255
```ts
256256
get empty() {
@@ -263,7 +263,7 @@ get empty() {
263263

264264
This property is used to indicate whether the label should be in the floating position. We'll
265265
use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
266-
Since the placeholder will be overlapping our control when when it's not floating, we should hide
266+
Since the placeholder will be overlapping our control when it's not floating, we should hide
267267
the `–` characters when it's not floating.
268268

269269
```ts
@@ -329,7 +329,7 @@ errorState = false;
329329
#### `controlType`
330330

331331
This property allows us to specify a unique string for the type of control in form field. The
332-
`<mat-form-field>` will add an additional class based on this type that can be used to easily apply
332+
`<mat-form-field>` will add a class based on this type that can be used to easily apply
333333
special styles to a `<mat-form-field>` that contains a specific type of control. In this example
334334
we'll use `example-tel-input` as our control type which will result in the form field adding the
335335
class `mat-form-field-type-example-tel-input`.
@@ -422,15 +422,15 @@ export class MyTelInput implements MatFormFieldControl<MyTel> {
422422
### Trying it out
423423

424424
Now that we've fully implemented the interface, we're ready to try our component out! All we need to
425-
do is place it inside of a `<mat-form-field>`
425+
do is place it inside a `<mat-form-field>`
426426

427427
```html
428428
<mat-form-field>
429429
<example-tel-input></example-tel-input>
430430
</mat-form-field>
431431
```
432432

433-
We also get all of the features that come with `<mat-form-field>` such as floating placeholder,
433+
We also get all the features that come with `<mat-form-field>` such as floating placeholder,
434434
prefix, suffix, hints, and errors (if we've given the form field an `NgControl` and correctly report
435435
the error state).
436436

‎guides/creating-a-custom-stepper-using-the-cdk-stepper.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ In the `app.component.css` file we can now style the stepper however we want:
100100

101101
## Using our new custom stepper component
102102

103-
Now we are ready to use our new custom stepper component and fill it with steps. Therefore we can, for example, add it to our `app.component.html` and define some steps:
103+
Now we are ready to use our new custom stepper component and fill it with steps. Therefore, we can, for example, add it to our `app.component.html` and define some steps:
104104

105105
**app.component.html**
106106

‎guides/customizing-component-styles.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Customizing Angular Material component styles
22

3-
### Styling concepts
3+
## Styling concepts
44

55
There are 3 questions to keep in mind while customizing the styles of Angular Material
66
components:
@@ -9,7 +9,7 @@ components:
99
2. Are your styles more specific than the defaults?
1010
3. Is the component a child of your component, or does it exist elsewhere in the DOM?
1111

12-
##### View encapsulation
12+
### View encapsulation
1313

1414
By default, Angular component styles are scoped to affect the component's view. This means that
1515
the styles you write will affect all the elements in your component template. They will *not*
@@ -20,23 +20,23 @@ also wish to take a look at
2020
[_The State of CSS in Angular_](https://blog.angular.io/the-state-of-css-in-angular-4a52d4bd2700)
2121
on the Angular blog.
2222

23-
##### Selector specificity
23+
### Selector specificity
2424

2525
Each CSS declaration has a level of *specificity* based on the type and number of selectors used.
2626
More specific styles will take precedence over less specific styles. Angular Material uses the
2727
least specific selectors possible for its components in order to make it easy to override them.
2828
You can read more about specificity and how it is calculated on the
2929
[MDN web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity).
3030

31-
##### Component location
31+
### Component location
3232

33-
Some Angular Material components, specifically overlay-based ones like MatDialog, MatSnackbar, etc.,
33+
Some Angular Material components, specifically overlay-based one's like MatDialog, MatSnackbar, etc.,
3434
do not exist as children of your component. Often they are injected elsewhere in the DOM. This is
3535
important to keep in mind, since even using high specificity and shadow-piercing selectors will
3636
not target elements that are not direct children of your component. Global styles are recommended
3737
for targeting such components.
3838

39-
### Styling overlay components
39+
## Styling overlay components
4040

4141
Overlay-based components have a `panelClass` property (or similar) that can be used to target the
4242
overlay pane. For example, to remove the padding from a dialog:
@@ -52,12 +52,12 @@ overlay pane. For example, to remove the padding from a dialog:
5252
this.dialog.open(MyDialogComponent, {panelClass: 'myapp-no-padding-dialog'})
5353
```
5454

55-
Since you are adding the styles to your global stylesheet, it is good practice to scope
55+
Since you are adding the styles to your global stylesheet, it is a good practice to scope
5656
them appropriately. Try prefixing your selector with your app name or "custom". Also note that
5757
the `mat-dialog-container`'s padding is added by default via a selector with specificity of 1. The
5858
customizing styles have a specificity of 2, so they will always take precedence.
5959

60-
### Styling other components
60+
## Styling other components
6161

6262
If your component has view encapsulation turned on (default), your component styles will only
6363
affect the top level children in your template. HTML elements belonging to child components cannot

‎guides/duplicate-theming-styles.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ extract the configuration for the color system from the theme.
6363
}
6464
```
6565

66-
#### Disabling duplication warnings
66+
## Disabling duplication warnings
6767

6868
If your application intentionally duplicates styles, a global Sass variable can be
6969
set to disable duplication warnings from Angular Material. For example:

‎guides/elevation.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Setting Element Elevation
2+
13
Angular Material's elevation classes and mixins allow you to add separation between elements along
24
the z-axis. All material design elements have resting elevations. In addition, some elements may
35
change their elevation in response to user interaction. The
@@ -7,7 +9,7 @@ explains how to best use elevation.
79
Angular Material provides two ways to control the elevation of elements: predefined CSS classes
810
and mixins.
911

10-
### Predefined CSS classes
12+
## Predefined CSS classes
1113

1214
The easiest way to add elevation to an element is to simply add one of the predefined CSS classes
1315
`mat-elevation-z#` where `#` is the elevation number you want, 0-24. Dynamic elevation can be
@@ -19,7 +21,7 @@ achieved by switching elevation classes:
1921

2022
<!-- example(elevation-overview) -->
2123

22-
### Mixins
24+
## Mixins
2325

2426
Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24
2527
indicating the elevation of the element as well as optional arguments for the elevation shadow's

‎guides/getting-started.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
# Getting Started with Angular Material
22

3-
This guide explains how to setup your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.
3+
This guide explains how to set up your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.
44

55
*Angular Resources*
66

77
If you are new to Angular or getting started with a new Angular application, see [Angular's full Getting Started Guide](https://angular.io/start) and [Setting up your environment](https://angular.io/guide/setup-local).
88

99
For existing applications, follow the steps below to begin using Angular Material.
1010

11-
### Install Angular Material
11+
## Install Angular Material
1212

13-
Use the Angular CLI's install [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:
13+
Use the Angular CLI's installation [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:
1414

1515
```bash
1616
ng add @angular/material
@@ -71,8 +71,8 @@ Run your local dev server:
7171
ng serve
7272
```
7373

74-
and point your browser to [http://localhost:4200](http://localhost:4200)
74+
Then point your browser to [http://localhost:4200](http://localhost:4200)
7575

7676
You should see the material slider component on the page.
7777

78-
In addition to the install schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.
78+
In addition to the installation schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.

‎guides/schematics.md

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1+
# Installation and Code Generation
2+
13
Angular Material comes packaged with Angular CLI schematics to make
24
creating Material applications easier.
35

4-
### Install Schematics
6+
## Install Schematics
7+
58
Schematics are included with both `@angular/cdk` and `@angular/material`. Once you install the npm
69
packages, they will be available through the Angular CLI.
710

811
Using the command below will install Angular Material, the [Component Dev Kit](https://material.angular.io/cdk) (CDK),
912
and [Angular Animations](https://angular.io/guide/animations) in your project. Then it will run the
10-
install schematic.
13+
installation schematic.
1114

1215
```
1316
ng add @angular/material
@@ -19,7 +22,7 @@ In case you just want to install the `@angular/cdk`, there are also schematics f
1922
ng add @angular/cdk
2023
```
2124

22-
The Angular Material `ng add` schematic helps you setup an Angular CLI project that uses Material. Running `ng add` will:
25+
The Angular Material `ng add` schematic helps you set up an Angular CLI project that uses Material. Running `ng add` will:
2326

2427
- Ensure [project dependencies](./getting-started#step-1-install-angular-material-angular-cdk-and-angular-animations) are placed in `package.json`
2528
- Enable the [BrowserAnimationsModule](./getting-started#step-2-configure-animations) your app module
@@ -33,7 +36,8 @@ The Angular Material `ng add` schematic helps you setup an Angular CLI project t
3336

3437

3538
## Component schematics
36-
In addition to the install schematic, Angular Material comes with multiple schematics that can be
39+
40+
In addition to the installation schematic, Angular Material comes with multiple schematics that can be
3741
used to easily generate Material Design components:
3842

3943

@@ -46,14 +50,14 @@ used to easily generate Material Design components:
4650
| `tree` | Component that interactively visualizes a nested folder structure by using the `<mat-tree>` component |
4751

4852

49-
Additionally the Angular CDK also comes with a collection of component schematics:
53+
Additionally, the Angular CDK also comes with a collection of component schematics:
5054

5155

5256
| Name | Description |
5357
|----------------|----------------------------------------------------------------------------------------------------|
5458
| `drag-drop` | Component that uses the `@angular/cdk/drag-drop` directives for creating an interactive to-do list |
5559

56-
#### Address form schematic
60+
### Address form schematic
5761

5862
Running the `address-form` schematic generates a new Angular component that can be used to get
5963
started with a Material Design form group consisting of:
@@ -66,40 +70,45 @@ started with a Material Design form group consisting of:
6670
ng generate @angular/material:address-form <component-name>
6771
```
6872

69-
#### Navigation schematic
73+
### Navigation schematic
74+
7075
The `navigation` schematic will create a new component that includes
71-
a toolbar with the app name and a responsive side nav based on Material
76+
a toolbar with the app name, and a responsive side nav based on Material
7277
breakpoints.
7378

7479
```
7580
ng generate @angular/material:navigation <component-name>
7681
```
7782

78-
#### Table schematic
83+
### Table schematic
84+
7985
The table schematic will create a component that renders an Angular Material `<table>` which has
8086
been pre-configured with a datasource for sorting and pagination.
8187

8288
```
8389
ng generate @angular/material:table <component-name>
8490
```
8591

86-
#### Dashboard schematic
92+
### Dashboard schematic
93+
8794
The `dashboard` schematic will create a new component that contains
8895
a dynamic grid list of Material Design cards.
8996

9097
```
9198
ng generate @angular/material:dashboard <component-name>
9299
```
93100

94-
#### Tree schematic
101+
### Tree schematic
102+
95103
The `tree` schematic can be used to quickly generate an Angular component that uses the Angular
96104
Material `<mat-tree>` component to visualize a nested folder structure.
97105

98106
```
99107
ng generate @angular/material:tree <component-name>
100108
```
101109

102-
#### Drag and Drop schematic
110+
### Drag and Drop schematic
111+
103112
The `drag-drop` schematic is provided by the `@angular/cdk` and can be used to generate a component
104113
that uses the CDK drag and drop directives.
105114

‎guides/theming-your-components.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
### Theming your custom component with Angular Material's theming system
1+
# Theming your custom component with Angular Material's theming system
2+
23
In order to style your own components with Angular Material's tooling, the component's styles must
34
be defined with Sass.
45

5-
#### 1. Define all color and typography styles in a "theme file" for the component
6+
## 1. Define all color and typography styles in a "theme file" for the component
7+
68
First, create a Sass mixin that accepts an Angular Material color configuration and
79
outputs the color-specific styles for the component. A color configuration is a Sass map.
810

@@ -70,12 +72,14 @@ individual theming systems (`color` and `typography`).
7072
See the [typography guide](https://material.angular.io/guide/typography) for more information on
7173
typographic customization.
7274

73-
#### 2. Define all remaining styles in a normal component stylesheet.
75+
## 2. Define all remaining styles in a normal component stylesheet
76+
7477
Define all styles unaffected by the theme in a separate file referenced directly in the component's
7578
`styleUrl`. This generally includes everything except for color and typography styles.
7679

7780

78-
#### 3. Include the theme mixin in your application
81+
## 3. Include the theme mixin in your application
82+
7983
Use the Sass `@include` keyword to include a component's theme mixin wherever you're already
8084
including Angular Material's built-in theme mixins.
8185

@@ -104,7 +108,8 @@ $theme: mat-light-theme((
104108
```
105109

106110

107-
#### Note: using the `mat-color` function to extract colors from a palette
111+
## Note: using the `mat-color` function to extract colors from a palette
112+
108113
You can consume the theming functions and Material Design color palettes from
109114
`@angular/material/theming`. The `mat-color` Sass function extracts a specific color from a palette.
110115
For example:

0 commit comments

Comments
 (0)