Progress bar documentation

packages/@react-spectrum/progress/docs/ProgressBar.mdx

@@ -0,0 +1,141 @@
+import {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-spectrum/progress';
+import {HeaderInfo, PropTable} from '@react-spectrum/docs';
+import packageData from '../package.json';
+
+```jsx import
+import {Flex} from '@react-spectrum/layout';
+import {ProgressBar} from '@react-spectrum/progress';
+import {View} from '@react-spectrum/view';
+```
+
+# ProgressBar
+
+<p>{docs.exports.ProgressBar.description}</p>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['ProgressBar']}
+  sourceData={[
+    {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/bar-loader/'}
+  ]} />
+
+## Example
+
+```tsx example
+<ProgressBar label="Loading…" value={50} />
+```
+
+## Value
+
+ProgressBars are controlled with the `value` prop representing current percentage (as an integer).
+In this case, the minimum and maximum values default to 0 and 100, respectively.
+
+```tsx example
+<ProgressBar label="Loading…" value={25} />
+```
+
+Alternatively, a different scale can be used by setting the `minValue` and `maxValue`.
+
+```tsx example
+<ProgressBar label="Loading…" minValue={50} maxValue={150} value={100} />
+```
+
+Values are formatted as a percentage by default, but can be modified by using the `formatOptions` for different formats.
+`formatOptions` is compatible with the option parameter of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) and is applied to the current locale.
+
+```tsx example
+<ProgressBar label="Loading…" formatOptions={{style: 'currency', currency: 'JPY'}} value={60} />
+```
+
+### Indeterminate
+[View guidelines](https://spectrum.adobe.com/page/bar-loader/#Determinate-or-indeterminate)
+
+By default, ProgressBars are determinate. Use a determinate ProgressBar when progress can be calculated against a specific goal.
+
+```tsx example
+<ProgressBar label="Loading…" value={50} />
+```
+
+Use an indeterminate ProgressBar when the wait time or effort to completion can not be determined.
+
+```tsx example
+<ProgressBar label="Loading…" isIndeterminate />
+```
+
+### Accessibility
+
+Depending on the visualization being used (i.e. depending on the `showValueLabel` prop), a `label`, `aria-label`, or `aria-labelledby` attribute is required.
+
+```tsx example
+<div>
+  <ProgressBar aria-labelledby="pc-label" showValueLabel={false} value={45} />
+  <label id="pc-label" style={{display: 'block'}}>Loading…</label>
+</div>
+```
+
+If using the over background variant, ensure the background offers enough contrast for the ProgressBar to be legible and meets color contrast guidelines.
+
+### Internationalization
+
+To internationalize a ProgressBar, a localized string should be passed to the `label` prop, `aria-label` prop, or value of the associated `aria-labelledby` element.
+
+For languages that are read right to left (e.g. Hebrew and Arabic), the layout is mirrored for both determinate and indeterminate options.
+
+## Labels
+[View guidelines](https://spectrum.adobe.com/page/bar-loader/#Label-or-no-label)
+
+Labels and value labels are shown by default on top, but they can also be moved to the side or hidden as needed.
+
+```tsx example
+<Flex flexDirection="column" maxWidth="250px">
+  <ProgressBar label="Loading…" marginBottom="25px" value={30} />
+  <ProgressBar label="Loading…" marginBottom="25px" labelPosition="side" value={30} />
+  <ProgressBar label="Loading…" showValueLabel={false} value={30} />
+</Flex>
+```
+
+Value labels by default show the percentage of progress in a determinate ProgressBar. These can be customized using the following props.
+
+`showValueLabel`: Hides the value label
+
+`formatOptions`: Allows you to customize the format of the percentage
+
+`valueLabel`: Allows you to customize the value label to any string.
+
+```tsx example
+<Flex flexDirection="column" maxWidth="250px">
+  <ProgressBar label="Loading…" marginBottom="25px" showValueLabel={false} value={30} />
+  <ProgressBar label="Loading…" marginBottom="25px" valueLabel="30 of 60 dogs" value={30} />
+  <ProgressBar label="Loading…" formatOptions={{style: 'percent', minimumFractionDigits: 2}} value={30.123} />
+</Flex>
+```
+
+## Props
+
+<PropTable component={docs.exports.ProgressBar} links={docs.links} />
+
+## Visual Options
+
+### Over background
+[View guidelines](https://spectrum.adobe.com/page/bar-loader/#Over-background)
+
+When a ProgressBar needs to be placed on top of a colored background, use the `overBackground` variant.
+
+```tsx example
+<View backgroundColor="positive" padding="25px">
+  <ProgressBar label="Loading…" variant="overBackground" value={5} />
+</View>
+```
+
+### Size
+[View guidelines](https://spectrum.adobe.com/page/bar-loader/#Size)
+
+```tsx example
+<Flex flexDirection="column">
+  <ProgressBar label="Small" marginBottom="25px" size="S" value={70} />
+  <ProgressBar label="Large" size="L" value={70} />
+</Flex>
+```

packages/@react-spectrum/progress/src/ProgressBar.tsx

@@ -42,5 +42,9 @@ function ProgressBar(props: SpectrumProgressBarProps, ref: DOMRef<HTMLDivElement
   );
 }
 
+/**
+ * ProgressBars show the progression of a system operation: downloading, uploading, processing, etc., in a visual way.
+ * They can represent either determinate or indeterminate progress.
+ */
 let _ProgressBar = React.forwardRef(ProgressBar);
 export {_ProgressBar as ProgressBar};

packages/@react-spectrum/progress/src/ProgressBarBase.tsx

@@ -53,7 +53,7 @@ function ProgressBarBase(props: ProgressBarBaseProps, ref: DOMRef<HTMLDivElement
     barStyle.width = `${Math.round(percentage * 100)}%`;
   }
 
-  // Ideally this should be in useProgressBar, but children 
+  // Ideally this should be in useProgressBar, but children
   // are not supported in ProgressCircle which shares that hook...
   if (!label && !ariaLabel && !ariaLabelledby) {
     console.warn('If you do not provide a visible label via children, you must specify an aria-label or aria-labelledby attribute for accessibility');