From 6e9b256eada6e9924378952dfc0adc79522cdc37 Mon Sep 17 00:00:00 2001 From: Matt Date: Fri, 25 Sep 2020 15:20:49 +0100 Subject: [PATCH] update docs --- .../{SimpleRating.js => BasicRating.js} | 0 .../{SimpleRating.tsx => BasicRating.tsx} | 0 docs/src/pages/components/rating/rating.md | 37 ++++++++++++------- .../pages/guides/migration-v4/migration-v4.md | 4 +- 4 files changed, 25 insertions(+), 16 deletions(-) rename docs/src/pages/components/rating/{SimpleRating.js => BasicRating.js} (100%) rename docs/src/pages/components/rating/{SimpleRating.tsx => BasicRating.tsx} (100%) diff --git a/docs/src/pages/components/rating/SimpleRating.js b/docs/src/pages/components/rating/BasicRating.js similarity index 100% rename from docs/src/pages/components/rating/SimpleRating.js rename to docs/src/pages/components/rating/BasicRating.js diff --git a/docs/src/pages/components/rating/SimpleRating.tsx b/docs/src/pages/components/rating/BasicRating.tsx similarity index 100% rename from docs/src/pages/components/rating/SimpleRating.tsx rename to docs/src/pages/components/rating/BasicRating.tsx diff --git a/docs/src/pages/components/rating/rating.md b/docs/src/pages/components/rating/rating.md index fefe99ee82f8b6..715ab7bb6d71f8 100644 --- a/docs/src/pages/components/rating/rating.md +++ b/docs/src/pages/components/rating/rating.md @@ -7,15 +7,15 @@ waiAria: https://www.w3.org/WAI/tutorials/forms/custom-controls/#a-star-rating # Rating -

Ratings provide insight regarding others’ opinions and experiences with a product. Users can also rate products they’ve purchased.

+

Ratings provide insight regarding others’ opinions and experiences, and can allow the user to submit a rating of thier own.

{{"component": "modules/components/ComponentLinkHeader.js"}} -## Simple ratings +## Basic rating -{{"demo": "pages/components/rating/SimpleRating.js"}} +{{"demo": "pages/components/rating/BasicRating.js"}} -## Customized ratings +## Customized rating Here are some examples of customizing the component. You can learn more about this in the [overrides documentation page](/customization/components/). @@ -24,12 +24,12 @@ Here are some examples of customizing the component. You can learn more about th ## Hover feedback -You can display a label on hover to help users pick the correct rating value. +You can display a label on hover to help the user pick the correct rating value. The demo uses the `onChangeActive` prop. {{"demo": "pages/components/rating/HoverRating.js"}} -## Half ratings +## Rating precision The rating can display any float number with the `value` prop. Use the `precision` prop to define the minimum increment value change allowed. @@ -38,22 +38,31 @@ Use the `precision` prop to define the minimum increment value change allowed. ## Sizes -Fancy larger or smaller ratings? Use the `size` prop. +For larger or smaller ratings use the `size` prop. {{"demo": "pages/components/rating/RatingSize.js"}} ## Accessibility -(WAI tutorial: https://www.w3.org/WAI/tutorials/forms/custom-controls/#a-star-rating) +([WAI tutorial](https://www.w3.org/WAI/tutorials/forms/custom-controls/#a-star-rating)) The accessibility of this component relies on: -- A radio group is used with its fields visually hidden. - It contains six radio buttons, one for each star and another for 0 stars, which is checked by default. Make sure you are providing a `name` prop that is unique to the parent form. -- The labels for the radio buttons contain actual text (“1 Star”, “2 Stars”, …), make sure you provide a `getLabelText` prop when the page language is not English. +- A radio group with its fields visually hidden. + It contains six radio buttons, one for each star, and another for 0 stars that is checked by default. Be sure to provide a value for the `name` prop that is unique to the parent form. +- Labels for the radio buttons containing actual text (“1 Star”, “2 Stars”, …). + Be sure to provide a suitable function to the `getLabelText` prop when the page is in a language other than English. +- A visually distinct appearance for the rating icons. + By default, the rating component uses both a difference of color and shape (filled and empty icons)to indicate the value. In the event that you are using color as the only means to indicate the value, the information should also be also displayed as text, as in this demo. This is important to match [success Criterion 1.4.1](https://www.w3.org/TR/WCAG21/#use-of-color) of WCAG2.1. -By default, the rating component uses both a difference of color and shape between the filled and empty icons to indicate the value. +{{"demo": "pages/components/rating/TextRating.js"}} -In the event that you are using color as the only means to indicate the value, the information should also be also displayed as text, as in this demo. This is important to match [success Criterion 1.4.1](https://www.w3.org/TR/WCAG21/#use-of-color) of WCAG2.1. +### ARIA -{{"demo": "pages/components/rating/TextRating.js"}} +The read only rating has a role of "img", and an aria-label that describes the displayed rating. + +### Keyboard + +Because the rating component uses radio buttons, keyboard interaction follows the native broser behavior. Tab will focus the current rating, and cursor keys control the selected rating. + +The read only rating is not focusable. diff --git a/docs/src/pages/guides/migration-v4/migration-v4.md b/docs/src/pages/guides/migration-v4/migration-v4.md index f6772b797508aa..05d904545851cd 100644 --- a/docs/src/pages/guides/migration-v4/migration-v4.md +++ b/docs/src/pages/guides/migration-v4/migration-v4.md @@ -527,8 +527,8 @@ const theme = createMuitheme({ - Move the component from the lab to the core. The component is now stable. ```diff - -import Alert from '@material-ui/lab/Rating'; - +import Alert from '@material-ui/core/Rating'; + -import Rating from '@material-ui/lab/Rating'; + +import Rating from '@material-ui/core/Rating'; ``` - Change the default empty icon to improve accessibility.