Skip to content

Commit f4d0c18

Browse files
jelbournjelbourn
authored
docs: update readme and add FAQ (#17814)
* Updates the readme to reflect the multi-package nature of the repo * Adds a Frequently Asked Questions page
1 parent 6ab86ff commit f4d0c18

File tree

2 files changed

+115
-120
lines changed

2 files changed

+115
-120
lines changed

‎FAQ.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Frequently Asked Questions
2+
3+
## Do Angular CDK and Angular Material support Shadow DOM?
4+
5+
While we don't _officially_ support Shadow DOM, we make a "best effort" to keep the components
6+
working in applications that do use Shadow DOM. This may change in the future based on the evolving
7+
browser landscape.
8+
9+
## What do the project labels mean?
10+
11+
Some labels are hopefully obvious, such as "feature" and "a11y". Other issues should all have
12+
descriptions on GitHub that outline how they're used. See our [labels page][labels] for the full
13+
descriptions.
14+
15+
## Are there any updates on issue _X_?
16+
17+
Any issue updates will appear on the issue. Due to the large volume of issues and feature requests
18+
recieved by the team, we aren't able to regularly comment on all open issues and PRs.
19+
20+
## Why hasn't PR _X_ been merged?
21+
22+
For every pull request, we run a presubmit against Google's internal test suite. This includes tests
23+
for all of the projects that use Angular CDK and Angular Material inside Google. As you might
24+
imagine, this process can be slow. Once this presubmit passes, PRs can generally be merged quickly.
25+
When tests fail, however, the team has to spend time investigating before the PR can be merged.
26+
[Google uses a single monolithic code repository for its code, which everything at head][monorepo].
27+
Because of this, we cannot merge any PRs that would break an existing project. If a PR has extensive
28+
failures, it may be put on the backburner until the team can schedule time to debug the full extent
29+
of the issue. If a PR seems ready to merge, but has been inactive, it has very likely
30+
encountered some test failures inside Google that must be resovled first.
31+
32+
## Why aren't you working on _X_?
33+
34+
Like any software team, we have limited time and resources. On top of the work we do in this repo,
35+
our team builds and maintains a smaller suite of Google-internal UI components and provides support
36+
to product teams inside Google using our components. We do our best to balance our time between bug
37+
fixes, support, and new feature work, but ultimately there will always be requests low on the
38+
priority queue.
39+
40+
## Can you help debug my app?
41+
42+
We can generally answer quick or straightforward questions. However, our team doesn't have the
43+
resources to provide more hands-on support. We recommend using [StackOverflow][] and [Gitter][] for
44+
more help.
45+
46+
## Why doesn't this repository provide support for application layouts?
47+
48+
Our team is focused on UI components and has decided to be agnostic to how those components are
49+
laid out. We suggest looking at existing layout systems in the front-end ecosystem, as well as
50+
using native CSS Flexbox and CSS Grid. For an Angular-oriented layout library,
51+
[`angular/flex-layout`][flex-layout] is a community-maintained project under the Angular umbrella.
52+
53+
## What's your relationship to [MDC Web][]?
54+
55+
MDC Web and Angular Material were created independently by two different teams inside Google.
56+
The Angular team is now working with the MDC team to share more code to reduce duplication. To that
57+
end, we are developing new, API-compatible versions of the Angular Material components backed by
58+
MDC Web. [See @jelbourn's 2019 ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891) for more details.
59+
60+
61+
[flex-layout]: https://github.com/angular/flex-layout/
62+
[StackOverflow]: https://stackoverflow.com
63+
[Gitter]: https://gitter.im/angular/material2
64+
[labels]: https://github.com/angular/components/labels
65+
[monorepo]: https://ai.google/research/pubs/pub45424/
66+
[MDC Web]: https://github.com/material-components/material-components-web/

‎README.md

Lines changed: 49 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,58 @@
1-
# Components and Material Design for Angular
2-
[![npm version](https://badge.fury.io/js/%40angular%2Fmaterial.svg)](https://www.npmjs.com/package/%40angular%2Fmaterial)
1+
# Official components for Angular
2+
[![npm version](https://badge.fury.io/js/%40angular%2Fcdk.svg)](https://www.npmjs.com/package/%40angular%cdk)
33
[![Build status](https://circleci.com/gh/angular/components.svg?style=svg)](https://circleci.com/gh/angular/components)
44
[![Gitter](https://badges.gitter.im/angular/components.svg)](https://gitter.im/angular/material2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
55

6-
This is the home for the Angular team's UI components built for and with Angular.
7-
These include Material Design components and the Angular Component Development Kit (CDK).
6+
The Angular team builds and maintains both common UI components and tools to help you build your
7+
own custom components. The team maintains several npm packages.
8+
9+
| Package | Description | Docs |
10+
|---------------------------|------------------------------------------------------------------------------------|------------------|
11+
| `@angular/cdk` | Library that helps you author custom UI components with common interation patterns | [Docs][cdk-docs] |
12+
| `@angular/material` | [Material Design][] UI components for Angular applications | [Docs][mat-docs] |
13+
| `@angular/google-maps` | Angular components built on top of the [Google Maps JavaScript API][] | [Docs][map-docs] |
14+
| `@angular/youtube-player` | Angular component built on top of the [YouTube Player API][] | [Docs][ytp-docs] |
15+
816

917
#### Quick links
10-
[Documentation, demos, and guides][aio] |
11-
[Google group](https://groups.google.com/forum/#!forum/angular-material2) |
18+
[Documentation, demos, and guides][mat-docs] |
19+
[Frequently Asked Questions][./FAQ] |
20+
[Community Google group](https://groups.google.com/forum/#!forum/angular-material2) |
1221
[Contributing](https://github.com/angular/components/blob/master/CONTRIBUTING.md) |
1322
[StackBlitz Template](https://stackblitz.com/fork/components-issue)
1423

15-
### Getting started
24+
## Getting started
1625

17-
See our [Getting Started Guide][getting-started]
18-
if you're building your first project with Angular Material.
26+
See our [Getting Started Guide][getting-started] if you're building your first project with Angular
27+
Material.
1928

20-
Check out our [directory of design documents](https://github.com/angular/components/wiki/Design-doc-directory)
21-
for more insight into our process.
2229

23-
If you'd like to contribute, you must follow our [contributing guidelines](https://github.com/angular/components/blob/master/CONTRIBUTING.md).
24-
You can look through the GitHub issues (which should be up-to-date on who is working on which features
25-
and which pieces are blocked) and make a comment.
30+
## Contributing
2631

27-
Please see our [`help wanted`](https://github.com/angular/components/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
28-
label for a list of issues where we could use help from the community.
32+
If you'd like to contribute, please follow our [contributing guidelines][contributing]. Please see
33+
our [`help wanted`][help-wanted] label for a list of issues with good opportunities for
34+
contribution.
2935

30-
#### High level stuff planned for Q4 2019 (Oct - Nov):
36+
## High level work planned for Q4 2019 (Oct - Dec):
3137
* Remove dependency on HammerJS
3238
* Finish remaining test harnesses for Angular Material components
3339
* Continuing to create new, API-compatible versions of the Angular Material components backed by
34-
MDC Web ([see @jelbourn's ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891)).
40+
[MDC Web][] ([see @jelbourn's ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891)).
3541
* New `@angular/google-maps` package
36-
* New `@angular/cdk/clipboard` subpackage
37-
38-
39-
#### Available features
40-
41-
| Feature | Notes | Docs |
42-
|------------------|--------------------------------------------------------|--------------|
43-
| autocomplete | | [Docs][24] |
44-
| badge | | [Docs][37] |
45-
| bottom-sheet | | [Docs][38] |
46-
| button | | [Docs][1] |
47-
| button-toggle | | [Docs][15] |
48-
| cards | | [Docs][2] |
49-
| checkbox | | [Docs][3] |
50-
| chips | | [Docs][26] |
51-
| data-table | | [Docs][28] |
52-
| datepicker | | [Docs][25] |
53-
| dialog | | [Docs][22] |
54-
| divider | | [Docs][35] |
55-
| drag-drop | | [Docs][39] |
56-
| expansion-panel | | [Docs][32] |
57-
| grid-list | | [Docs][9] |
58-
| icon | | [Docs][10] |
59-
| input | | [Docs][5] |
60-
| list | | [Docs][8] |
61-
| menu | | [Docs][17] |
62-
| paginator | | [Docs][29] |
63-
| progress-bar | | [Docs][12] |
64-
| progress-spinner | | [Docs][11] |
65-
| radio | | [Docs][4] |
66-
| ripples | | [Docs][19] |
67-
| select | | [Docs][23] |
68-
| sidenav | | [Docs][6] |
69-
| slide-toggle | | [Docs][14] |
70-
| slider | | [Docs][16] |
71-
| snackbar / toast | | [Docs][21] |
72-
| sort-header | | [Docs][30] |
73-
| stepper | | [Docs][33] |
74-
| tabs | | [Docs][13] |
75-
| textarea | | [Docs][5] |
76-
| toolbar | | [Docs][7] |
77-
| tooltip | | [Docs][18] |
78-
| tree | | [Docs][36] |
79-
| virtual-scroll | | [Docs][40] |
80-
| ---------------- | ------------------------------------------------------ | ------------ |
81-
| theming | | [Guide][20] |
82-
| typography | | [Guide][27] |
83-
| layout | See [CDK Layout][cdk-layout] or [@angular/flex-layout][lay_rp]| - |
84-
| cdk | | [Docs][34] |
85-
86-
[1]: https://material.angular.io/components/button/overview
87-
[2]: https://material.angular.io/components/card/overview
88-
[3]: https://material.angular.io/components/checkbox/overview
89-
[4]: https://material.angular.io/components/radio/overview
90-
[5]: https://material.angular.io/components/input/overview
91-
[6]: https://material.angular.io/components/sidenav/overview
92-
[7]: https://material.angular.io/components/toolbar/overview
93-
[8]: https://material.angular.io/components/list/overview
94-
[9]: https://material.angular.io/components/grid-list/overview
95-
[10]: https://material.angular.io/components/icon/overview
96-
[11]: https://material.angular.io/components/progress-spinner/overview
97-
[12]: https://material.angular.io/components/progress-bar/overview
98-
[13]: https://material.angular.io/components/tabs/overview
99-
[14]: https://material.angular.io/components/slide-toggle/overview
100-
[15]: https://material.angular.io/components/button-toggle/overview
101-
[16]: https://material.angular.io/components/slider/overview
102-
[17]: https://material.angular.io/components/menu/overview
103-
[18]: https://material.angular.io/components/tooltip/overview
104-
[19]: https://material.angular.io/components/ripple/overview
105-
[20]: https://material.angular.io/guide/theming
106-
[21]: https://material.angular.io/components/snack-bar/overview
107-
[22]: https://material.angular.io/components/dialog/overview
108-
[23]: https://material.angular.io/components/select/overview
109-
[24]: https://material.angular.io/components/autocomplete/overview
110-
[25]: https://material.angular.io/components/datepicker/overview
111-
[26]: https://material.angular.io/components/chips/overview
112-
[27]: https://material.angular.io/guide/typography
113-
[28]: https://material.angular.io/components/table/overview
114-
[29]: https://material.angular.io/components/paginator/overview
115-
[30]: https://material.angular.io/components/sort/overview
116-
117-
[32]: https://material.angular.io/components/expansion/overview
118-
[33]: https://material.angular.io/components/stepper/overview
119-
[34]: https://material.angular.io/cdk/categories
120-
[35]: https://material.angular.io/components/divider/overview
121-
[36]: https://material.angular.io/components/tree/overview
122-
[37]: https://material.angular.io/components/badge/overview
123-
[38]: https://material.angular.io/components/bottom-sheet/overview
124-
[39]: https://material.angular.io/cdk/drag-drop/overview
125-
[40]: https://material.angular.io/cdk/scrolling/overview#virtual-scrolling
126-
127-
[aio]: https://material.angular.io
128-
[getting-started]: https://material.angular.io/guide/getting-started
129-
[lay_rp]: https://github.com/angular/flex-layout
130-
[cdk-layout]: https://material.angular.io/cdk/layout/overview
42+
* New `@angular/cdk/clipboard` subpackage
43+
13144

45+
## About the team
46+
The Angular Components team is part of the Angular team at Google. The team includes both Google
47+
employees and community contributors from around the globe.
13248

133-
## The goal of Angular Material and the CDK
134-
Our goal is to build a set of high-quality UI components built with Angular and TypeScript.
135-
These include foundational components and services, found in the CDK, and components that follow
136-
the Material Design spec. These components serve as an example of how to build Angular UI components
137-
that follow best practices.
49+
Our team has two primary goals:
50+
* Build high-quality UI components that developers can drop into existing applications
51+
* Provide tools that help developers build their own custom components with common interaction
52+
patterns
13853

139-
### What do we mean by "high-quality"?
54+
55+
What do we mean by "high-quality" components?
14056
* Internationalized and accessible so that all users can use them.
14157
* Straightforward APIs that don't confuse developers.
14258
* Behave as expected across a wide variety of use-cases without bugs.
@@ -146,7 +62,7 @@ that follow best practices.
14662
* Code is clean and well-documented to serve as an example for Angular developers.
14763

14864
## Browser and screen reader support
149-
Angular Material supports the most recent two versions of all major browsers:
65+
The Angular Components team supports the most recent two versions of all major browsers:
15066
Chrome (including Android), Firefox, Safari (including iOS), and IE11 / Edge.
15167

15268
We aim for great user experience with the following screen readers:
@@ -155,3 +71,16 @@ We aim for great user experience with the following screen readers:
15571
* **iOS**: VoiceOver with Safari
15672
* **Android**: Android Accessibility Suite (formerly TalkBack) with Chrome.
15773
* **Chrome OS**: ChromeVox with Chrome.
74+
75+
76+
[Material Design]: https://material.io
77+
[Google Maps JavaScript API]: https://developers.google.com/maps/documentation/javascript/tutorial
78+
[YouTube Player API]: https://developers.google.com/youtube/iframe_api_reference
79+
[MDC Web]: https://github.com/material-components/material-components-web/
80+
[cdk-docs]: https://material.angular.io/cdk/categories
81+
[mat-docs]: https://material.angular.io
82+
[map-docs]: https://github.com/angular/components/blob/master/src/google-maps/README.md
83+
[ytp-docs]: https://github.com/angular/components/blob/master/src/youtube-player/README.md
84+
[getting-started]: https://material.angular.io/guide/getting-started
85+
[contributing]: https://github.com/angular/components/blob/master/CONTRIBUTING.md
86+
[help-wanted]: https://github.com/angular/components/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22

0 commit comments

Comments
 (0)