diff --git a/packages/react-components/react-progress/Spec.md b/packages/react-components/react-progress/Spec.md index 1b00c0be365b5..3ccc354c4ef3f 100644 --- a/packages/react-components/react-progress/Spec.md +++ b/packages/react-components/react-progress/Spec.md @@ -2,62 +2,104 @@ ## Background -_Description and use cases of this component_ +The `Progress` component is used to display the current progress of an operation flow. ## Prior Art -_Include background research done for this component_ +### Open UI -- _Link to Open UI research_ -- _Link to comparison of v7 and v0_ -- _Link to GitHub epic issue for the converged component_ +| Library | Component Name | Spec Link | Notes | +| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | +| Ant Design | Progress | [Progress](https://ant.design/components/progress/) | Specifies the type, a combined progress component | +| Atlassian Design | Progress bar | [ProgressBar](https://atlassian.design/components/progress-bar/success-progress-bar/examples) | Defaults to determinate state, which turns green when value reaches 1. Has an indeterminate state | +| Bootstrap | Progress | [Progress](https://getbootstrap.com/docs/4.3/components/progress/) | Allows for multiple different animation styles on the same Progress bar | +| Carbon Design | Progress Indicator | [ProgressIndicator](https://react.carbondesignsystem.com/?path=/story/components-progressindicator--default) | Determinate Progress that has steps, similar to a Slider | +| Fast | Progress | [Progress](https://explore.fast.design/components/fast-progress) | Combined Progress and Spinner component, has a determinate and indeterminate state | +| Lightning Design System | Progress Bar | [ProgressBar](https://www.lightningdesignsystem.com/components/progress-bar/) | Has a vertical bar, only determinate, and can specify progress step | +| Semantic UI | Progress | [Progress](https://semantic-ui.com/modules/progress.html#indicating) | Allows for success and error states, default rounded edges. No indeterminate form | + +### Comparison of v8 and v0 + +The existing components are: + +- v8 + - `ProgressIndicator` +- v0 ## Sample Code -_Provide some representative example code that uses the proposed API for the component_ +Basic example: + +```jsx +import { Progress } from '@fluentui/react-progress'; + +function App() { + return ; +} +``` ## Variants -_Describe visual or functional variants of this control, if applicable. For example, a slider could have a 2D variant._ +- Indeterminate Progress + - The default Progress that animates indefinitely +- Determinate Progress + - The determinate form of the Progress component that incrementally loads from 0% to 100% + +### Shape + +The Progress is represented as a rounded rectangular area with an inner animated bar that either travels across the area indefinitely or animates up till a specified point ## API -_List the **Props** and **Slots** proposed for the component. Ideally this would just be a link to the component's `.types.ts` file_ +### Slots + +- `root` - The root element of the Progress. The html element is a `div` +- `bar` - The div element that gets animated into a Progress bar. The html element is `div` +- `track` - The div element that functions as the track for the Progress bar. The html element is `div` +- `label` - The text shown above the Progress. The html element is a `span` +- `description` - The text shown below the Progress. The html element is a `span` + +### Props + +See API at [Progress.types.tsx](./src/components/Progress/Progress.types.ts). ## Structure -- _**Public**_ -- _**Internal**_ -- _**DOM** - how the component will be rendered as HTML elements_ +```html +
+ + Loading... + +
+ +
+ + Loading Text +
+``` ## Migration -_Describe what will need to be done to upgrade from the existing implementations:_ - -- _Migration from v8_ -- _Migration from v0_ +See [MIGRATION.md](./MIGRATION.md). ## Behaviors -_Explain how the component will behave in use, including:_ +### States -- _Component States_ -- _Interaction_ - - _Keyboard_ - - _Cursor_ - - _Touch_ - - _Screen readers_ +- **Display** - The Progress will use the following priority: -## Accessibility + - Specifying the `percentComplete` from `0` to `1` will alter the Progress from indeterminate to determinate. + - The component also has `rtl` support and will animate the progress bar from right to left if set. + +### Interaction + +The Progress is non-interactive. -Base accessibility information is included in the design document. After the spec is filled and review, outcomes from it need to be communicated to design and incorporated in the design document. - -- Decide whether to use **native element** or folow **ARIA** and provide reasons -- Identify the **[ARIA](https://www.w3.org/TR/wai-aria-practices-1.2/) pattern** and, if the component is listed there, follow its specification as possible. -- Identify accessibility **variants**, the `role` ([ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#role_definitions)) of the component, its `slots` and `aria-*` props. -- Describe the **keyboard navigation**: Tab Oder and Arrow Key Navigation. Describe any other keyboard **shortcuts** used -- Specify texts for **state change announcements** - [ARIA live regions - ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) (number of available items in dropdown, error messages, confirmations, ...) -- Identify UI parts that appear on **hover or focus** and specify keyboard and screen reader interaction with them -- List cases when **focus** needs to be **trapped** in sections of the UI (for dialogs and popups or for hierarchical navigation) -- List cases when **focus** needs to be **moved programatically** (if parts of the UI are appearing/disappearing or other cases) +- **Keyboard** - Not keyboard focusable. +- **Mouse** + + - Click: No action + +- **Touch** - Nothing + +## Accessibility