Skip to content

Add Progress SPEC #24418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tomi-msft merged 5 commits into from
Oct 4, 2022
Merged

Add Progress SPEC #24418

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3bdae90
Add Progress SPEC
tomi-msft Aug 18, 2022
c9061e9
Apply suggestions from code review
tomi-msft Sep 27, 2022
4ed0b00
Update spec
tomi-msft Sep 27, 2022
93e0725
Update SPEC
tomi-msft Sep 28, 2022
9a2153f
Merge branch 'master' of https://github.com/OfficeDev/office-ui-fabri…
tomi-msft Oct 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 76 additions & 34 deletions packages/react-components/react-progress/Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

@layershifter layershifter Aug 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see a reference there to OpenUI, is the title correct?

Copy link
Member

@khmakoto khmakoto Sep 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tomi-msft you can add a link to Open UI if there is a page about Progress there. If a page for progress does not exist feel free to rename this section to something like "Comparison between other libraries".


- _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 <Progress thickness="large" label="Loading" />;
}
```

## 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
Copy link
Member

@layershifter layershifter Aug 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be great to include there an image with a component's anatomy so it would be clearer which slots correspond to what area.

Copy link
Contributor

@behowell behowell Sep 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want to use Field to add support for the label and description. It also looks like the visual spec includes support for error and success states, which the Field component already supports.

That would mean:

  • The Progress control only has two slots:
    • root (which would be the track)
    • bar (child of root)
  • There's a new ProgresField control that wraps Progress and adds the features of Field: label, helperText, validationState, etc.

That would follow the pattern of our other form controls, which (mostly) don't include labels built-in. And it would also benefit from sharing all of the features of Field.

Copy link
Member

@khmakoto khmakoto Sep 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with this but I think we discussed maybe making those changes to both spec and implementation in a separate PR.


- `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).
Copy link
Member

@layershifter layershifter Aug 24, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: it's currently empty:

image

It would be great to include currently implemented props from #24023 to the spec.

Copy link
Contributor

@behowell behowell Sep 30, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should make the props align with the HTML <progress> element:

  • Use value instead of percentComplete
  • Add a max prop that defaults to 1.0
  • Remove the indeterminate prop, and just use the value prop: the progress bar is indeterminate if value is undefined.


## Structure

- _**Public**_
- _**Internal**_
- _**DOM** - how the component will be rendered as HTML elements_
```html
<div class="fui-Progress">
<!-- Label for Progress -->
<span className="fui-Progress__label">Loading...</span>
<!-- Track for Progress -->
<div class="fui-Progress__track" />
<!-- Bar for Progress -->
<div class="fui-Progess__bar" />
<!-- Label for Progress description -->
<span className="fui-Progress__description">Loading Text</span>
</div>
```

## 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