From 5316b0dd67891fec60a594622da2194e88344abf Mon Sep 17 00:00:00 2001 From: Jeremy Elbourn Date: Mon, 25 Nov 2019 16:29:06 -0800 Subject: [PATCH] docs: update readme and add FAQ * Updates the readme to reflect the multi-package nature of the repo * Adds a Frequently Asked Questions page --- FAQ.md | 66 +++++++++++++++++++++ README.md | 169 ++++++++++++++++-------------------------------------- 2 files changed, 115 insertions(+), 120 deletions(-) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 000000000000..e7c2027f5006 --- /dev/null +++ b/FAQ.md @@ -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/ diff --git a/README.md b/README.md index a00022557ece..f855282d53bf 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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: @@ -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