Skip to content

Commit

Permalink
docs: update readme and add FAQ (angular#17814)
Browse files Browse the repository at this point in the history 
* Updates the readme to reflect the multi-package nature of the repo
* Adds a Frequently Asked Questions page
  • Loading branch information
@jelbourn
jelbourn committed Dec 3, 2019
1 parent 6ab86ff commit f4d0c18
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 120 deletions.
66 changes: 66 additions & 0 deletions FAQ.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Frequently Asked Questions

## Do Angular CDK and Angular Material support Shadow DOM?

While we don't _officially_ support Shadow DOM, we make a "best effort" to keep the components
working in applications that do use Shadow DOM. This may change in the future based on the evolving
browser landscape.

## What do the project labels mean?

Some labels are hopefully obvious, such as "feature" and "a11y". Other issues should all have
descriptions on GitHub that outline how they're used. See our [labels page][labels] for the full
descriptions.

## Are there any updates on issue _X_?

Any issue updates will appear on the issue. Due to the large volume of issues and feature requests
recieved by the team, we aren't able to regularly comment on all open issues and PRs.

## Why hasn't PR _X_ been merged?

For every pull request, we run a presubmit against Google's internal test suite. This includes tests
for all of the projects that use Angular CDK and Angular Material inside Google. As you might
imagine, this process can be slow. Once this presubmit passes, PRs can generally be merged quickly.
When tests fail, however, the team has to spend time investigating before the PR can be merged.
[Google uses a single monolithic code repository for its code, which everything at head][monorepo].
Because of this, we cannot merge any PRs that would break an existing project. If a PR has extensive
failures, it may be put on the backburner until the team can schedule time to debug the full extent
of the issue. If a PR seems ready to merge, but has been inactive, it has very likely
encountered some test failures inside Google that must be resovled first.

## Why aren't you working on _X_?

Like any software team, we have limited time and resources. On top of the work we do in this repo,
our team builds and maintains a smaller suite of Google-internal UI components and provides support
to product teams inside Google using our components. We do our best to balance our time between bug
fixes, support, and new feature work, but ultimately there will always be requests low on the
priority queue.

## Can you help debug my app?

We can generally answer quick or straightforward questions. However, our team doesn't have the
resources to provide more hands-on support. We recommend using [StackOverflow][] and [Gitter][] for
more help.

## Why doesn't this repository provide support for application layouts?

Our team is focused on UI components and has decided to be agnostic to how those components are
laid out. We suggest looking at existing layout systems in the front-end ecosystem, as well as
using native CSS Flexbox and CSS Grid. For an Angular-oriented layout library,
[`angular/flex-layout`][flex-layout] is a community-maintained project under the Angular umbrella.

## What's your relationship to [MDC Web][]?

MDC Web and Angular Material were created independently by two different teams inside Google.
The Angular team is now working with the MDC team to share more code to reduce duplication. To that
end, we are developing new, API-compatible versions of the Angular Material components backed by
MDC Web. [See @jelbourn's 2019 ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891) for more details.


[flex-layout]: https://github.com/angular/flex-layout/
[StackOverflow]: https://stackoverflow.com
[Gitter]: https://gitter.im/angular/material2
[labels]: https://github.com/angular/components/labels
[monorepo]: https://ai.google/research/pubs/pub45424/
[MDC Web]: https://github.com/material-components/material-components-web/
169 changes: 49 additions & 120 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,142 +1,58 @@
# Components and Material Design for Angular
[![npm version](https://badge.fury.io/js/%40angular%2Fmaterial.svg)](https://www.npmjs.com/package/%40angular%2Fmaterial)
# Official components for Angular
[![npm version](https://badge.fury.io/js/%40angular%2Fcdk.svg)](https://www.npmjs.com/package/%40angular%cdk)
[![Build status](https://circleci.com/gh/angular/components.svg?style=svg)](https://circleci.com/gh/angular/components)
[![Gitter](https://badges.gitter.im/angular/components.svg)](https://gitter.im/angular/material2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

This is the home for the Angular team's UI components built for and with Angular.
These include Material Design components and the Angular Component Development Kit (CDK).
The Angular team builds and maintains both common UI components and tools to help you build your
own custom components. The team maintains several npm packages.

| Package | Description | Docs |
|---------------------------|------------------------------------------------------------------------------------|------------------|
| `@angular/cdk` | Library that helps you author custom UI components with common interation patterns | [Docs][cdk-docs] |
| `@angular/material` | [Material Design][] UI components for Angular applications | [Docs][mat-docs] |
| `@angular/google-maps` | Angular components built on top of the [Google Maps JavaScript API][] | [Docs][map-docs] |
| `@angular/youtube-player` | Angular component built on top of the [YouTube Player API][] | [Docs][ytp-docs] |


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

### Getting started
## Getting started

See our [Getting Started Guide][getting-started]
if you're building your first project with Angular Material.
See our [Getting Started Guide][getting-started] if you're building your first project with Angular
Material.

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

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

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

#### High level stuff planned for Q4 2019 (Oct - Nov):
## High level work planned for Q4 2019 (Oct - Dec):
* Remove dependency on HammerJS
* Finish remaining test harnesses for Angular Material components
* Continuing to create new, API-compatible versions of the Angular Material components backed by
MDC Web ([see @jelbourn's ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891)).
[MDC Web][] ([see @jelbourn's ng-conf talk](https://youtu.be/4EXQKP-Sihw?t=891)).
* New `@angular/google-maps` package
* New `@angular/cdk/clipboard` subpackage


#### Available features

| Feature | Notes | Docs |
|------------------|--------------------------------------------------------|--------------|
| autocomplete | | [Docs][24] |
| badge | | [Docs][37] |
| bottom-sheet | | [Docs][38] |
| button | | [Docs][1] |
| button-toggle | | [Docs][15] |
| cards | | [Docs][2] |
| checkbox | | [Docs][3] |
| chips | | [Docs][26] |
| data-table | | [Docs][28] |
| datepicker | | [Docs][25] |
| dialog | | [Docs][22] |
| divider | | [Docs][35] |
| drag-drop | | [Docs][39] |
| expansion-panel | | [Docs][32] |
| grid-list | | [Docs][9] |
| icon | | [Docs][10] |
| input | | [Docs][5] |
| list | | [Docs][8] |
| menu | | [Docs][17] |
| paginator | | [Docs][29] |
| progress-bar | | [Docs][12] |
| progress-spinner | | [Docs][11] |
| radio | | [Docs][4] |
| ripples | | [Docs][19] |
| select | | [Docs][23] |
| sidenav | | [Docs][6] |
| slide-toggle | | [Docs][14] |
| slider | | [Docs][16] |
| snackbar / toast | | [Docs][21] |
| sort-header | | [Docs][30] |
| stepper | | [Docs][33] |
| tabs | | [Docs][13] |
| textarea | | [Docs][5] |
| toolbar | | [Docs][7] |
| tooltip | | [Docs][18] |
| tree | | [Docs][36] |
| virtual-scroll | | [Docs][40] |
| ---------------- | ------------------------------------------------------ | ------------ |
| theming | | [Guide][20] |
| typography | | [Guide][27] |
| layout | See [CDK Layout][cdk-layout] or [@angular/flex-layout][lay_rp]| - |
| cdk | | [Docs][34] |

[1]: https://material.angular.io/components/button/overview
[2]: https://material.angular.io/components/card/overview
[3]: https://material.angular.io/components/checkbox/overview
[4]: https://material.angular.io/components/radio/overview
[5]: https://material.angular.io/components/input/overview
[6]: https://material.angular.io/components/sidenav/overview
[7]: https://material.angular.io/components/toolbar/overview
[8]: https://material.angular.io/components/list/overview
[9]: https://material.angular.io/components/grid-list/overview
[10]: https://material.angular.io/components/icon/overview
[11]: https://material.angular.io/components/progress-spinner/overview
[12]: https://material.angular.io/components/progress-bar/overview
[13]: https://material.angular.io/components/tabs/overview
[14]: https://material.angular.io/components/slide-toggle/overview
[15]: https://material.angular.io/components/button-toggle/overview
[16]: https://material.angular.io/components/slider/overview
[17]: https://material.angular.io/components/menu/overview
[18]: https://material.angular.io/components/tooltip/overview
[19]: https://material.angular.io/components/ripple/overview
[20]: https://material.angular.io/guide/theming
[21]: https://material.angular.io/components/snack-bar/overview
[22]: https://material.angular.io/components/dialog/overview
[23]: https://material.angular.io/components/select/overview
[24]: https://material.angular.io/components/autocomplete/overview
[25]: https://material.angular.io/components/datepicker/overview
[26]: https://material.angular.io/components/chips/overview
[27]: https://material.angular.io/guide/typography
[28]: https://material.angular.io/components/table/overview
[29]: https://material.angular.io/components/paginator/overview
[30]: https://material.angular.io/components/sort/overview

[32]: https://material.angular.io/components/expansion/overview
[33]: https://material.angular.io/components/stepper/overview
[34]: https://material.angular.io/cdk/categories
[35]: https://material.angular.io/components/divider/overview
[36]: https://material.angular.io/components/tree/overview
[37]: https://material.angular.io/components/badge/overview
[38]: https://material.angular.io/components/bottom-sheet/overview
[39]: https://material.angular.io/cdk/drag-drop/overview
[40]: https://material.angular.io/cdk/scrolling/overview#virtual-scrolling

[aio]: https://material.angular.io
[getting-started]: https://material.angular.io/guide/getting-started
[lay_rp]: https://github.com/angular/flex-layout
[cdk-layout]: https://material.angular.io/cdk/layout/overview
* New `@angular/cdk/clipboard` subpackage


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

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

### What do we mean by "high-quality"?

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

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

We aim for great user experience with the following screen readers:
Expand All @@ -155,3 +71,16 @@ We aim for great user experience with the following screen readers:
* **iOS**: VoiceOver with Safari
* **Android**: Android Accessibility Suite (formerly TalkBack) with Chrome.
* **Chrome OS**: ChromeVox with Chrome.


[Material Design]: https://material.io
[Google Maps JavaScript API]: https://developers.google.com/maps/documentation/javascript/tutorial
[YouTube Player API]: https://developers.google.com/youtube/iframe_api_reference
[MDC Web]: https://github.com/material-components/material-components-web/
[cdk-docs]: https://material.angular.io/cdk/categories
[mat-docs]: https://material.angular.io
[map-docs]: https://github.com/angular/components/blob/master/src/google-maps/README.md
[ytp-docs]: https://github.com/angular/components/blob/master/src/youtube-player/README.md
[getting-started]: https://material.angular.io/guide/getting-started
[contributing]: https://github.com/angular/components/blob/master/CONTRIBUTING.md
[help-wanted]: https://github.com/angular/components/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22

0 comments on commit f4d0c18

Please sign in to comment.