chore(Progress): updated placement and verbiage of status examples (#11988)

* chore(Progress): updated placement and verbiage of status examples

* Updated snapshot

* Update packages/react-core/src/components/Progress/examples/Progress.md

Co-authored-by: Erin Donehoo <[email protected]>

* Update packages/react-core/src/components/Progress/examples/Progress.md

Co-authored-by: Erin Donehoo <[email protected]>

* Update packages/react-core/src/components/Progress/examples/Progress.md

Co-authored-by: Erin Donehoo <[email protected]>

---------

Co-authored-by: Eric Olkowski <[email protected]>
Co-authored-by: Erin Donehoo <[email protected]>

Author: thatblindgeye

packages/react-core/src/components/MultipleFileUpload/MultipleFileUploadStatusItem.tsx

@@ -50,6 +50,8 @@ export interface MultipleFileUploadStatusItemProps extends React.HTMLProps<HTMLL
   progressAriaLabel?: string;
   /** Associates the progress bar with it's label for accessibility purposes. Required when title not used */
   progressAriaLabelledBy?: string;
+  /** Adds an accessible description to the ProgressBar via space separated list of ids. Required when helperText is passed in. */
+  progressAriaDescribedBy?: string;
   /** Modifies the text announced by assistive technologies when the progress bar updates. */
   progressAriaLiveMessage?: string | ((loadPercentage: number) => string);
   /** Unique identifier for progress. Generated if not specified. */
@@ -74,6 +76,7 @@ export const MultipleFileUploadStatusItem: React.FunctionComponent<MultipleFileU
   progressVariant,
   progressAriaLabel,
   progressAriaLabelledBy,
+  progressAriaDescribedBy,
   progressId,
   progressAriaLiveMessage,
   buttonAriaLabel = 'Remove from list',
@@ -161,6 +164,7 @@ export const MultipleFileUploadStatusItem: React.FunctionComponent<MultipleFileU
           variant={variant}
           aria-label={progressAriaLabel}
           aria-labelledby={progressAriaLabelledBy}
+          aria-describedby={progressAriaDescribedBy}
           id={progressId}
           helperText={progressHelperText}
         />

packages/react-core/src/components/MultipleFileUpload/examples/MultipleFileUploadBasic.tsx

@@ -96,11 +96,11 @@ export const MultipleFileUploadBasic: React.FunctionComponent = () => {
   };
 
   // add helper text to a status item showing any error encountered during the file reading process
-  const createHelperText = (file: File) => {
+  const createHelperText = (file: File, fileIndex: number) => {
     const fileResult = readFileData.find((readFile) => readFile.fileName === file.name);
     if (fileResult?.loadError) {
       return (
-        <HelperText isLiveRegion>
+        <HelperText id={`multiple-file-upload-basic-example-help-text-${fileIndex}`} isLiveRegion>
           <HelperTextItem variant="error">{fileResult.loadError.toString()}</HelperTextItem>
         </HelperText>
       );
@@ -135,14 +135,15 @@ export const MultipleFileUploadBasic: React.FunctionComponent = () => {
             statusToggleIcon={statusIcon}
             aria-label="Current uploads"
           >
-            {currentFiles.map((file) => (
+            {currentFiles.map((file, index) => (
               <MultipleFileUploadStatusItem
                 file={file}
                 key={file.name}
                 onClearClick={() => removeFiles([file.name])}
                 onReadSuccess={handleReadSuccess}
                 onReadFail={handleReadFail}
-                progressHelperText={createHelperText(file)}
+                progressHelperText={createHelperText(file, index)}
+                progressAriaDescribedBy={`multiple-file-upload-basic-example-help-text-${index}`}
               />
             ))}
           </MultipleFileUploadStatus>

packages/react-core/src/components/Progress/Progress.tsx

@@ -42,6 +42,8 @@ export interface ProgressProps extends Omit<React.HTMLProps<HTMLDivElement>, 'si
   'aria-label'?: string;
   /** Associates the ProgressBar with it's label for accessibility purposes. Required when title not used */
   'aria-labelledby'?: string;
+  /** Adds an accessible description to the ProgressBar via space separated list of ids. Required when helperText is passed in. */
+  'aria-describedby'?: string;
   /** Content which can be used to convey additional information about the progress component.
    * We recommend the helper text component as it was designed for this purpose.
    */
@@ -65,7 +67,8 @@ class Progress extends Component<ProgressProps> {
     isTitleTruncated: false,
     tooltipPosition: 'top' as 'auto' | 'top' | 'bottom' | 'left' | 'right',
     'aria-label': null as string,
-    'aria-labelledby': null as string
+    'aria-labelledby': null as string,
+    'aria-describedby': null as string
   };
 
   id = this.props.id || getUniqueId();
@@ -89,6 +92,7 @@ class Progress extends Component<ProgressProps> {
       tooltipPosition,
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledBy,
+      'aria-describedby': ariaDescribedBy,
       helperText,
       ...props
     } = this.props;
@@ -107,6 +111,10 @@ class Progress extends Component<ProgressProps> {
       progressBarAriaProps['aria-label'] = ariaLabel;
     }
 
+    if (ariaDescribedBy) {
+      progressBarAriaProps['aria-describedby'] = ariaDescribedBy;
+    }
+
     if (valueText) {
       progressBarAriaProps['aria-valuetext'] = valueText;
     }

packages/react-core/src/components/Progress/ProgressBar.tsx

@@ -4,6 +4,7 @@ import { css } from '@patternfly/react-styles';
 export interface AriaProps {
   'aria-labelledby'?: string;
   'aria-label'?: string;
+  'aria-describedby'?: string;
   'aria-valuemin'?: number;
   'aria-valuenow'?: number;
   'aria-valuemax'?: number;
@@ -28,7 +29,7 @@ export const ProgressBar: React.FunctionComponent<ProgressBarProps> = ({
   value,
   ...props
 }: ProgressBarProps) => (
-  <div {...props} className={css(styles.progressBar, className)} {...progressBarAriaProps}>
+  <div role="progressbar" {...props} className={css(styles.progressBar, className)} {...progressBarAriaProps}>
     <div className={css(styles.progressIndicator)} style={{ width: `${value}%` }}>
       <span className={css(styles.progressMeasure)}>{children}</span>
     </div>

packages/react-core/src/components/Progress/ProgressContainer.tsx

@@ -130,7 +130,7 @@ export const ProgressContainer: React.FunctionComponent<ProgressContainerProps>
           )}
         </div>
       )}
-      <ProgressBar role="progressbar" progressBarAriaProps={progressBarAriaProps} value={value}>
+      <ProgressBar progressBarAriaProps={progressBarAriaProps} value={value}>
         {measureLocation === ProgressMeasureLocation.inside && `${value}%`}
       </ProgressBar>
       {helperText && <ProgressHelperText>{helperText}</ProgressHelperText>}

packages/react-core/src/components/Progress/__tests__/Generated/__snapshots__/ProgressBar.test.tsx.snap

@@ -4,6 +4,7 @@ exports[`ProgressBar should match snapshot (auto-generated) 1`] = `
 <DocumentFragment>
   <div
     class="pf-v6-c-progress__bar ''"
+    role="progressbar"
   >
     <div
       class="pf-v6-c-progress__indicator"

packages/react-core/src/components/Progress/__tests__/ProgressBar.test.tsx

@@ -0,0 +1,19 @@
+import { render, screen } from '@testing-library/react';
+import { ProgressBar } from '../ProgressBar';
+
+test('Does not render with aria-describedby by default', () => {
+  render(<ProgressBar value={33} />);
+
+  expect(screen.getByRole('progressbar')).not.toHaveAccessibleDescription();
+});
+
+test('Renders with aria-describedby when progressBarAriaProps is passed in', () => {
+  render(
+    <>
+      <div id="test-id">Test description</div>
+      <ProgressBar value={33} progressBarAriaProps={{ 'aria-describedby': 'test-id' }} />
+    </>
+  );
+
+  expect(screen.getByRole('progressbar')).toHaveAccessibleDescription('Test description');
+});

packages/react-core/src/components/Progress/examples/Progress.md

@@ -8,75 +8,119 @@ propComponents: ['Progress']
 import { useState } from 'react';
 
 ## Examples
+
 ### Basic
+
 ```ts file="./ProgressBasic.tsx"
+
 ```
 
 ### Small
+
 ```ts file="./ProgressSmall.tsx"
+
 ```
 
 ### Large
+
 ```ts file="./ProgressLarge.tsx"
-```
 
-### Outside
-```ts file="./ProgressOutside.tsx"
 ```
 
-### Inside
-```ts file="./ProgressInside.tsx"
-```
+### Outside
 
-### Success
-```ts file="./ProgressSuccess.tsx"
-```
+```ts file="./ProgressOutside.tsx"
 
-### Failure
-```ts file="./ProgressFailure.tsx"
 ```
 
-### Warning
-```ts file="./ProgressWarning.tsx"
-```
+### Inside
 
-### Inside success
-```ts file="./ProgressInsideSuccess.tsx"
-```
+```ts file="./ProgressInside.tsx"
 
-### Outside failure
-```ts file="./ProgressOutsideFailure.tsx"
 ```
 
 ### Single line
+
 ```ts file="./ProgressSingleLine.tsx"
+
 ```
 
 ### Without measure
+
 ```ts file="./ProgressWithoutMeasure.tsx"
-```
 
-### Failure without measure
-```ts file="./ProgressFailureWithoutMeasure.tsx"
 ```
 
-
 ### Finite step
+
 ```ts file="./ProgressFiniteStep.tsx"
+
 ```
 
 ### Progress with step instructions
+
 ```ts file="./ProgressStepInstruction.tsx"
+
 ```
 
 ### Truncate title
+
 ```ts file="./ProgressTruncateTitle.tsx"
+
 ```
 
 ### Title outside of progress bar
+
 ```ts file="./ProgressTitleOutsideOfProgressBar.tsx"
+
 ```
 
 ### Helper text
+
 ```ts file="./ProgressHelperText.tsx"
+
+```
+
+## Status examples
+
+When conveying status, you should ensure:
+
+- There is visible helper text that explains the status.
+- The helper text includes the status icon, as seen in our [basic helper text example](/components/helper-text#basic).
+- The helper text is linked to the `<Progress>` component via the `aria-describedby` property, as seen in the [progress helper text example](#helper-text).
+
+### Success
+
+```ts file="./ProgressSuccess.tsx"
+
+```
+
+### Failure
+
+```ts file="./ProgressFailure.tsx"
+
+```
+
+### Warning
+
+```ts file="./ProgressWarning.tsx"
+
+```
+
+### Inside success
+
+```ts file="./ProgressInsideSuccess.tsx"
+
+```
+
+### Outside failure
+
+```ts file="./ProgressOutsideFailure.tsx"
+
+```
+
+### Failure without measure
+
+```ts file="./ProgressFailureWithoutMeasure.tsx"
+
 ```

packages/react-core/src/components/Progress/examples/ProgressHelperText.tsx

@@ -25,7 +25,7 @@ export const ProgressHelperText: React.FunctionComponent = () => {
   const helperTextVariant = selectedVariant === 'danger' ? 'error' : selectedVariant;
 
   const helperText = (
-    <HelperText>
+    <HelperText id="progress-helper-text-example-help-text">
       <HelperTextItem variant={helperTextVariant}>
         {`${formatVariantName(selectedVariant)} variant is being displayed`}
       </HelperTextItem>
@@ -36,7 +36,13 @@ export const ProgressHelperText: React.FunctionComponent = () => {
     <>
       {variantOptions}
       <br />
-      <Progress value={33} title="Title" helperText={helperText} variant={selectedVariant} />
+      <Progress
+        aria-describedby="progress-helper-text-example-help-text"
+        value={33}
+        title="Title"
+        helperText={helperText}
+        variant={selectedVariant}
+      />
     </>
   );
 };