Merge branch 'master' into poc/hook-api-links

docs/data/joy/components/circular-progress/circular-progress.md

@@ -7,71 +7,70 @@ githubLabel: 'component: CircularProgress'
 
 # Circular Progress
 
-<p class="description">Circular Progress indicators, commonly known as spinners, express an unspecified wait time or display the length of a process.</p>
+<p class="description">The Circular Progress component showcases the duration of a process or an indefinite wait period.</p>
 
 ## Introduction
 
-Progress indicators inform users about the status of ongoing processes, such as loading an app, submitting a form, or saving updates.
+A 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.
+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}}
 
-## Component
+:::info
+The component's animations rely primarily on CSS to ensure that it functions even before JavaScript loads.
+:::
 
-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 <CircularProgress />;
-}
 ```
 
-### Variants
-
-The circular progress component supports the four global variants: `solid`, `soft` (default), `outlined`, and `plain`.
+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.
 
-{{"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`.
+Circular Progress 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, any children nested inside the Circular Progress will be centered.
 
 {{"demo": "CircularProgressChildren.js"}}
 
@@ -81,16 +80,45 @@ 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 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
+
+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 `<span>` with an `<svg>` component that wraps around two `<circle>`.
+
+```html
+<span role="progressbar" class="MuiCircularProgress-root">
+  <svg class="MuiCircularProgress-svg">
+    <circle class="MuiCircularProgress-track"></circle>
+    <circle class="MuiCircularProgress-progress"></circle>
+  </svg>
+  <!-- children are nested here when present -->
+</span>
+```

docs/data/joy/components/radio-button/RadioButtonsGroup.js

@@ -16,12 +16,12 @@ export default function RadioButtonsGroup() {
           slotProps={{ input: { 'aria-describedby': 'female-helper-text' } }}
         />
         <FormHelperText id="female-helper-text">
-          A helper text for this radio.
+          Helper text for this radio.
         </FormHelperText>
         <Radio value="male" label="Male" />
         <Radio value="other" label="Other" />
       </RadioGroup>
-      <FormHelperText>This is a helper text.</FormHelperText>
+      <FormHelperText>This is helper text.</FormHelperText>
     </FormControl>
   );
 }

docs/data/joy/components/radio-button/RadioButtonsGroup.tsx

@@ -16,12 +16,12 @@ export default function RadioButtonsGroup() {
           slotProps={{ input: { 'aria-describedby': 'female-helper-text' } }}
         />
         <FormHelperText id="female-helper-text">
-          A helper text for this radio.
+          Helper text for this radio.
         </FormHelperText>
         <Radio value="male" label="Male" />
         <Radio value="other" label="Other" />
       </RadioGroup>
-      <FormHelperText>This is a helper text.</FormHelperText>
+      <FormHelperText>This is helper text.</FormHelperText>
     </FormControl>
   );
 }

docs/data/joy/components/radio-button/RadioButtonsGroup.tsx.preview

@@ -7,10 +7,10 @@
       slotProps={{ input: { 'aria-describedby': 'female-helper-text' } }}
     />
     <FormHelperText id="female-helper-text">
-      A helper text for this radio.
+      Helper text for this radio.
     </FormHelperText>
     <Radio value="male" label="Male" />
     <Radio value="other" label="Other" />
   </RadioGroup>
-  <FormHelperText>This is a helper text.</FormHelperText>
+  <FormHelperText>This is helper text.</FormHelperText>
 </FormControl>

docs/data/joy/components/radio-button/RadioColors.js

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioColors() {
+  return (
+    <FormControl>
+      <FormLabel>Colors</FormLabel>
+      <RadioGroup defaultValue="medium" name="radio-buttons-group">
+        <Radio value="primary" label="Primary" color="primary" />
+        <Radio value="neutral" label="Neutral" color="neutral" />
+        <Radio value="danger" label="Danger" color="danger" />
+        <Radio value="info" label="Info" color="info" />
+        <Radio value="success" label="Success" color="success" />
+        <Radio value="warning" label="Warning" color="warning" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioColors.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioColors() {
+  return (
+    <FormControl>
+      <FormLabel>Colors</FormLabel>
+      <RadioGroup defaultValue="medium" name="radio-buttons-group">
+        <Radio value="primary" label="Primary" color="primary" />
+        <Radio value="neutral" label="Neutral" color="neutral" />
+        <Radio value="danger" label="Danger" color="danger" />
+        <Radio value="info" label="Info" color="info" />
+        <Radio value="success" label="Success" color="success" />
+        <Radio value="warning" label="Warning" color="warning" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioColors.tsx.preview

@@ -0,0 +1,11 @@
+<FormControl>
+  <FormLabel>Colors</FormLabel>
+  <RadioGroup defaultValue="medium" name="radio-buttons-group">
+    <Radio value="primary" label="Primary" color="primary" />
+    <Radio value="neutral" label="Neutral" color="neutral" />
+    <Radio value="danger" label="Danger" color="danger" />
+    <Radio value="info" label="Info" color="info" />
+    <Radio value="success" label="Success" color="success" />
+    <Radio value="warning" label="Warning" color="warning" />
+  </RadioGroup>
+</FormControl>

docs/data/joy/components/radio-button/RadioSizes.js

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioSizes() {
+  return (
+    <FormControl>
+      <FormLabel>Sizes</FormLabel>
+      <RadioGroup defaultValue="medium" name="radio-buttons-group">
+        <Radio value="small" label="Small" size="sm" />
+        <Radio value="medium" label="Medium" size="md" />
+        <Radio value="large" label="Large" size="lg" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioSizes.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioSizes() {
+  return (
+    <FormControl>
+      <FormLabel>Sizes</FormLabel>
+      <RadioGroup defaultValue="medium" name="radio-buttons-group">
+        <Radio value="small" label="Small" size="sm" />
+        <Radio value="medium" label="Medium" size="md" />
+        <Radio value="large" label="Large" size="lg" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioSizes.tsx.preview

@@ -0,0 +1,8 @@
+<FormControl>
+  <FormLabel>Sizes</FormLabel>
+  <RadioGroup defaultValue="medium" name="radio-buttons-group">
+    <Radio value="small" label="Small" size="sm" />
+    <Radio value="medium" label="Medium" size="md" />
+    <Radio value="large" label="Large" size="lg" />
+  </RadioGroup>
+</FormControl>

docs/data/joy/components/radio-button/RadioVariants.js

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioVariants() {
+  return (
+    <FormControl>
+      <FormLabel>Variants</FormLabel>
+      <RadioGroup defaultValue="outlined" name="radio-buttons-group">
+        <Radio value="outlined" label="Outlined" variant="outlined" />
+        <Radio value="soft" label="Soft" variant="soft" />
+        <Radio value="solid" label="Solid" variant="solid" />
+        <Radio value="plain" label="Plain" variant="plain" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioVariants.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import FormControl from '@mui/joy/FormControl';
+import FormLabel from '@mui/joy/FormLabel';
+import Radio from '@mui/joy/Radio';
+import RadioGroup from '@mui/joy/RadioGroup';
+
+export default function RadioVariants() {
+  return (
+    <FormControl>
+      <FormLabel>Variants</FormLabel>
+      <RadioGroup defaultValue="outlined" name="radio-buttons-group">
+        <Radio value="outlined" label="Outlined" variant="outlined" />
+        <Radio value="soft" label="Soft" variant="soft" />
+        <Radio value="solid" label="Solid" variant="solid" />
+        <Radio value="plain" label="Plain" variant="plain" />
+      </RadioGroup>
+    </FormControl>
+  );
+}

docs/data/joy/components/radio-button/RadioVariants.tsx.preview

@@ -0,0 +1,9 @@
+<FormControl>
+  <FormLabel>Variants</FormLabel>
+  <RadioGroup defaultValue="outlined" name="radio-buttons-group">
+    <Radio value="outlined" label="Outlined" variant="outlined" />
+    <Radio value="soft" label="Soft" variant="soft" />
+    <Radio value="solid" label="Solid" variant="solid" />
+    <Radio value="plain" label="Plain" variant="plain" />
+  </RadioGroup>
+</FormControl>