From 33b2f6149a9fb83c4bf5c80d36ae2f3376c7a812 Mon Sep 17 00:00:00 2001 From: gerrardsarah Date: Thu, 9 Feb 2023 19:54:46 -0800 Subject: [PATCH 1/3] circular progress doc --- .../circular-progress/circular-progress.md | 76 ++++++++++++------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/docs/data/joy/components/circular-progress/circular-progress.md b/docs/data/joy/components/circular-progress/circular-progress.md index 0d9fb8d37898a6..b7f0665caa5feb 100644 --- a/docs/data/joy/components/circular-progress/circular-progress.md +++ b/docs/data/joy/components/circular-progress/circular-progress.md @@ -6,71 +6,70 @@ githubLabel: 'component: CircularProgress' # Circular Progress -

Circular Progress indicators, commonly known as spinners, express an unspecified wait time or display the length of a process.

+

The Circular Progress component showcases the duration of a process or an indefinite wait period.

## Introduction -Progress indicators inform users about the status of ongoing processes, such as loading an app, submitting a form, or saving updates. +The Circular Progress Indicator, often referred to as a Spinner, is a visual representation of the progress of an operation or task. -The `CircularProgress` is indeterminate by default, indicating an unspecified wait time. -To actually have it represent how long an operation will take, use the [determinate](#determinate) mode. - -The animations of the components rely on CSS as much as possible to work even before the JavaScript is loaded. +`CircularProgress` defaults to indeterminate, signifying an undefined wait duration. +If you'd like to represent how long an operation will take, you can use [determinate](#determinate) mode. {{"demo": "CircularProgressUsage.js", "hideToolbar": true, "bg": "gradient"}} {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} -## Component +:::info +The animations of the components rely on CSS as much as possible to work, even before the JavaScript is loaded. +::: -After [installation](/joy-ui/getting-started/installation/), you can start building with this component using the following basic elements: +## Basics ```jsx import CircularProgress from '@mui/joy/CircularProgress'; - -export default function MyApp() { - return ; -} ``` -### Variants - -The circular progress component supports the four global variants: `solid`, `soft` (default), `outlined`, and `plain`. +`CircularProgress` provides users with updates on the status of ongoing processes such as loading an app, submitting a form, or saving updates. -{{"demo": "CircularProgressVariants.js"}} +## Customization -### Colors +### Variants -Every palette included in the theme is available via the `color` prop. -Play around combining different colors. +The Circular Progress component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid` (default), `soft`, `outlined`, and `plain`. -{{"demo": "CircularProgressColors.js"}} +{{"demo": "CircularProgressVariants.js"}} ### Sizes -The circular progress component comes with three sizes out of the box: `sm`, `md` (default), and `lg`. +The Circular progress component comes in three sizes: `sm`, `md` (default), and `lg`. {{"demo": "CircularProgressSizes.js"}} :::info -To learn how to add more sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). +To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes). ::: -### Determinate +### Colors -You can use the `determinate` prop if you want to indicate a specified wait time. +Every palette included in the theme is available via the `color` prop. -{{"demo": "CircularProgressDeterminate.js"}} +{{"demo": "CircularProgressColors.js"}} ### Thickness -Provides a number to `thickness` prop to control the circle's stroke width. +You can use the `thickness` prop to control the circle's stroke width. {{"demo": "CircularProgressThickness.js"}} +### Determinate + +The `determinate` prop lets you indicate a specified wait time. + +{{"demo": "CircularProgressDeterminate.js"}} + ### Children -The circular progress component places the provided children in the center by default. +By default, the circular progress component places any children in the center. {{"demo": "CircularProgressChildren.js"}} @@ -90,6 +89,27 @@ The size of the circular progress is controlled by a button, an icon button, or Play around with all the CSS variables available on the component to see how the design changes. -You can use those to customize the component on both the `sx` prop and the theme. +You can use these to customize the component with both the `sx` prop and the theme. {{"demo": "CircularProgressVariables.js", "hideToolbar": true}} + +## Accessibility + +When creating your circular progress component, ensure sufficient color contrast between the it and the background, using a minimum of [WCAG 2.0's color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1. + +## Anatomy + +The Circular Progress component is composed of a single root `` with an `` component that wraps around two ``. + +```html + + + + + + +``` From 490cbe9a18fe23cb776b39d0adbe72348f69fe2b Mon Sep 17 00:00:00 2001 From: Sarah Gerrard <98355961+LadyBluenotes@users.noreply.github.com> Date: Thu, 16 Feb 2023 22:51:57 -0800 Subject: [PATCH 2/3] edits made as per comments --- .../circular-progress/circular-progress.md | 35 ++++++++++++------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/data/joy/components/circular-progress/circular-progress.md b/docs/data/joy/components/circular-progress/circular-progress.md index b7f0665caa5feb..4473027b60a3de 100644 --- a/docs/data/joy/components/circular-progress/circular-progress.md +++ b/docs/data/joy/components/circular-progress/circular-progress.md @@ -10,17 +10,17 @@ githubLabel: 'component: CircularProgress' ## Introduction -The Circular Progress Indicator, often referred to as a Spinner, is a visual representation of the progress of an operation or task. +A circular progress indicator, often referred to as a spinner, is a visual representation of the progress of an operation or task. -`CircularProgress` defaults to indeterminate, signifying an undefined wait duration. -If you'd like to represent how long an operation will take, you can use [determinate](#determinate) mode. +The Circular Progress component defaults to indeterminate, signifying an undefined wait duration. +Use [determinate](#determinate) mode to indicate how long a given operation will take. {{"demo": "CircularProgressUsage.js", "hideToolbar": true, "bg": "gradient"}} {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} :::info -The animations of the components rely on CSS as much as possible to work, even before the JavaScript is loaded. +The component's animations rely primarily on CSS to ensure that it functions even before JavaScript loads. ::: ## Basics @@ -29,7 +29,7 @@ The animations of the components rely on CSS as much as possible to work, even b import CircularProgress from '@mui/joy/CircularProgress'; ``` -`CircularProgress` provides users with updates on the status of ongoing processes such as loading an app, submitting a form, or saving updates. +The Circular Progress component provides users with updates on the status of ongoing processes such as loading an app, submitting a form, or saving updates. ## Customization @@ -41,7 +41,7 @@ The Circular Progress component supports Joy UI's four [global variants](/joy-ui ### Sizes -The Circular progress component comes in three sizes: `sm`, `md` (default), and `lg`. +Circular Progress comes in three sizes: `sm`, `md` (default), and `lg`. {{"demo": "CircularProgressSizes.js"}} @@ -69,7 +69,7 @@ The `determinate` prop lets you indicate a specified wait time. ### Children -By default, the circular progress component places any children in the center. +By default, any children nested inside the Circular Progress will be centered. {{"demo": "CircularProgressChildren.js"}} @@ -95,21 +95,30 @@ You can use these to customize the component with both the `sx` prop and the the ## Accessibility -When creating your circular progress component, ensure sufficient color contrast between the it and the background, using a minimum of [WCAG 2.0's color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1. +Out of the box, the `aria-valuenow` attribute will indicate the current value of the progress bar only when the value is not indeterminate. +This attribute will display the value as a percentage. + +Here are a few tips to make sure you have an accessible circular progress component: + +- When creating your circular progress component, ensure sufficient color contrast between it and the background, using a minimum of [WCAG 2.0's color contrast ratio](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html) of 4.5:1. +- To define a human-readable text alternative to `aria-valuenow`, the `aria-valuetext` will show the current value in a more user-friendly way. + For example, downloading files might be conveyed as `aria-valuetext="8% (34 minutes) remaining`. +- The `aria-valuemin` and `aria-valuemax` attributes are commonly used to indicate the minimum and maximum values of a range. + By default, these attributes are set to 0 and 100, respectively. + If you need to set a different minimum or maximum value for your range, you can use the these attributes to do so. +- Use the `aria-label` or `aria-labelledby` attribute to provide an accessible name for your progress component. + These define the string value or identifies the element(s) that label the progress component. ## Anatomy The Circular Progress component is composed of a single root `` with an `` component that wraps around two ``. ```html - + + ``` From 05b5cd88373fc2694c132ff1fa6a8151196c1e23 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Mon, 27 Mar 2023 13:09:39 -0500 Subject: [PATCH 3/3] tiny copy edits --- .../joy/components/circular-progress/circular-progress.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/data/joy/components/circular-progress/circular-progress.md b/docs/data/joy/components/circular-progress/circular-progress.md index 4473027b60a3de..87ed646bb590b9 100644 --- a/docs/data/joy/components/circular-progress/circular-progress.md +++ b/docs/data/joy/components/circular-progress/circular-progress.md @@ -79,16 +79,15 @@ For plain texts and icons, the dimension is relative to the circular progress's ### With a button -`CircularProgress` can be used as a decorator to show loading on a button. +The Circular Progress component can be used as a decorator to show loading on a button. -The size of the circular progress is controlled by a button, an icon button, or a link unless the `size` prop is explicitly specified on the progress. +The size of the Circular Progress is controlled by a button, an icon button, or a link unless the `size` prop is explicitly specified on the progress. {{"demo": "CircularProgressButton.js"}} -## CSS variables +## CSS variable playground Play around with all the CSS variables available on the component to see how the design changes. - You can use these to customize the component with both the `sx` prop and the theme. {{"demo": "CircularProgressVariables.js", "hideToolbar": true}}