From a6a24bb6620aa7b833ff8f73756f95bde595b600 Mon Sep 17 00:00:00 2001 From: Uyen Doan <56598021+smmr-dn@users.noreply.github.com> Date: Tue, 8 Oct 2024 09:12:56 -0500 Subject: [PATCH] Updated documentation for Progress Indicators (#2271) --- .../src/content/docs/progressindicator.mdx | 92 ++++++++++++++++--- examples/ProgressIndicators.main.css | 6 ++ examples/ProgressIndicators.main.jsx | 15 +++ examples/ProgressIndicators.value.css | 6 ++ examples/ProgressIndicators.value.jsx | 15 +++ examples/ProgressLinear.isAnimated.css | 6 ++ examples/ProgressLinear.isAnimated.jsx | 37 ++++++++ examples/ProgressLinear.label.css | 6 ++ ...near.main.jsx => ProgressLinear.label.jsx} | 3 +- examples/ProgressLinear.main.css | 3 - examples/ProgressLinear.status.css | 6 ++ examples/ProgressLinear.status.jsx | 28 ++++++ examples/ProgressRadial.content.jsx | 14 +++ examples/ProgressRadial.size.css | 6 ++ examples/ProgressRadial.size.jsx | 17 ++++ examples/ProgressRadial.status.css | 6 ++ examples/ProgressRadial.status.jsx | 16 ++++ ...dial.main.jsx => ProgressRadial.value.jsx} | 2 +- examples/index.tsx | 52 +++++++++-- 19 files changed, 311 insertions(+), 25 deletions(-) create mode 100644 examples/ProgressIndicators.main.css create mode 100644 examples/ProgressIndicators.main.jsx create mode 100644 examples/ProgressIndicators.value.css create mode 100644 examples/ProgressIndicators.value.jsx create mode 100644 examples/ProgressLinear.isAnimated.css create mode 100644 examples/ProgressLinear.isAnimated.jsx create mode 100644 examples/ProgressLinear.label.css rename examples/{ProgressLinear.main.jsx => ProgressLinear.label.jsx} (79%) delete mode 100644 examples/ProgressLinear.main.css create mode 100644 examples/ProgressLinear.status.css create mode 100644 examples/ProgressLinear.status.jsx create mode 100644 examples/ProgressRadial.content.jsx create mode 100644 examples/ProgressRadial.size.css create mode 100644 examples/ProgressRadial.size.jsx create mode 100644 examples/ProgressRadial.status.css create mode 100644 examples/ProgressRadial.status.jsx rename examples/{ProgressRadial.main.jsx => ProgressRadial.value.jsx} (91%) diff --git a/apps/website/src/content/docs/progressindicator.mdx b/apps/website/src/content/docs/progressindicator.mdx index d2656072a41..bc704111106 100644 --- a/apps/website/src/content/docs/progressindicator.mdx +++ b/apps/website/src/content/docs/progressindicator.mdx @@ -1,37 +1,105 @@ --- title: Progress indicator -description: Progress indicators express an unspecified wait time or display the length of a process. +description: Progress indicators express the length of in-progress operations. thumbnail: ProgressIndicator ---

{frontmatter.description}

-## Progress linear +## Usage - +There are two types of progress indicators available as separate components: - - +- `ProgressLinear`: shows progress on a linear bar. +- `ProgressRadial`: shows progress in a circular form. + + + -### Props +By default, the progress indicators are considered to be "indeterminate". This is useful for short processes, where it isn't necessary (or possible) to indicate the completion percentage. For longer processes, a "determinate" progress indicator should be used. - +### Value -## Progress radial +To specify a value for determinate progress indicator, the `value` prop can be used. This prop is available for both `ProgressLinear` and `ProgressRadial`. The value must be inclusively between `0` and `100`, representing what percentage of the task has been completed. - + + + - - +Exclusively for `ProgressLinear`, the `isAnimated` flag is helpful when applying animation to the indicator as the value changes. + + + +**Note**: If the `indeterminate` prop is set to `true`, this value will be ignored. + +### Status + +The `status` prop can be used to convey the outcome of a process. The recommended UX flow is to display the default progress indicator during the loading process, and then update the `status` to reflect whether the process was successful, encountered an error, or requires attention. + +Three available statuses are: + +- `"positive"`: to indicate success. +- `"negative"`: to indicate failure. +- `"warning"`: to indicate a cautionary state or partial success. + + + + + +When using the `status` prop, each `ProgressRadial` is accompanied by a status icon, which provides a visual cue to inform the current progress state better. The status icon can also be replaced by custom [content](#content) for more advanced uses. + + + + + +### Label + +Indicator labels can be passed into the `labels` prop as an array. If one label is passed, it will be centered. If there are two labels, each is pushed to one end of the progress indicator. This prop is only available for `ProgressLinear`. + + + + + +### Size + +Four `size` options available are: + +- `"x-small"` +- `"small"` +- `"medium"` (default) +- `"large"` + +This prop is only available for `ProgressRadial`. + + + + + +### Content + +The `ProgressRadial` component can be wrapped around JSX elements, such as icons or texts. This content helps provide flexibility to enhance the progress display with additional visual appearance. This prop is only available for `ProgressRadial`. + + + + + +**Note**: Indicators of `"x-small"` size will not display its content. + ## Accessibility To make the progress indicator accessible to non-sighted users, a visually-hidden "Loading" message will be automatically included when the `value` is not set to 100%. To further improve the experience, applications should have a mechanism to inform users once the loading process is complete. Depending on the criticality of the content and how long it takes to load, the progress completion can be indicated using a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions), or by programmatically moving focus to the top of the new content. -### Props +## Props + +### ProgressLinear + + + +### ProgressRadial diff --git a/examples/ProgressIndicators.main.css b/examples/ProgressIndicators.main.css new file mode 100644 index 00000000000..2a54a8f32ee --- /dev/null +++ b/examples/ProgressIndicators.main.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: column; + width: 200px; + gap: var(--iui-size-s); +} diff --git a/examples/ProgressIndicators.main.jsx b/examples/ProgressIndicators.main.jsx new file mode 100644 index 00000000000..be78467a292 --- /dev/null +++ b/examples/ProgressIndicators.main.jsx @@ -0,0 +1,15 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressLinear, ProgressRadial } from '@itwin/itwinui-react'; + +export default () => { + return ( +
+ + +
+ ); +}; diff --git a/examples/ProgressIndicators.value.css b/examples/ProgressIndicators.value.css new file mode 100644 index 00000000000..2a54a8f32ee --- /dev/null +++ b/examples/ProgressIndicators.value.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: column; + width: 200px; + gap: var(--iui-size-s); +} diff --git a/examples/ProgressIndicators.value.jsx b/examples/ProgressIndicators.value.jsx new file mode 100644 index 00000000000..9a5f36a3483 --- /dev/null +++ b/examples/ProgressIndicators.value.jsx @@ -0,0 +1,15 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressLinear, ProgressRadial } from '@itwin/itwinui-react'; + +export default () => { + return ( +
+ + +
+ ); +}; diff --git a/examples/ProgressLinear.isAnimated.css b/examples/ProgressLinear.isAnimated.css new file mode 100644 index 00000000000..47d2d6fe27b --- /dev/null +++ b/examples/ProgressLinear.isAnimated.css @@ -0,0 +1,6 @@ +.demo-container { + width: 200px; + display: flex; + flex-direction: column; + gap: var(--iui-size-xs); +} diff --git a/examples/ProgressLinear.isAnimated.jsx b/examples/ProgressLinear.isAnimated.jsx new file mode 100644 index 00000000000..3aa00a300b0 --- /dev/null +++ b/examples/ProgressLinear.isAnimated.jsx @@ -0,0 +1,37 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { Button, ProgressLinear } from '@itwin/itwinui-react'; + +export default () => { + const [value, setValue] = React.useState(0); + const isDone = value === 100; + + React.useEffect(() => { + let interval; + + if (!isDone) { + interval = setInterval( + () => setValue((prevValue) => prevValue + 20), + 1500, + ); + } + + return () => clearInterval(interval); + }, [isDone]); + + return ( +
+ + +
+ ); +}; diff --git a/examples/ProgressLinear.label.css b/examples/ProgressLinear.label.css new file mode 100644 index 00000000000..8cc0a04ee6d --- /dev/null +++ b/examples/ProgressLinear.label.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: column; + gap: var(--iui-size-s); + width: min(100%, 200px); +} diff --git a/examples/ProgressLinear.main.jsx b/examples/ProgressLinear.label.jsx similarity index 79% rename from examples/ProgressLinear.main.jsx rename to examples/ProgressLinear.label.jsx index 356e47d395a..50ffdf93fe1 100644 --- a/examples/ProgressLinear.main.jsx +++ b/examples/ProgressLinear.label.jsx @@ -8,7 +8,8 @@ import { ProgressLinear } from '@itwin/itwinui-react'; export default () => { return (
- + +
); }; diff --git a/examples/ProgressLinear.main.css b/examples/ProgressLinear.main.css deleted file mode 100644 index b4f72ba9f1f..00000000000 --- a/examples/ProgressLinear.main.css +++ /dev/null @@ -1,3 +0,0 @@ -.demo-container { - width: min(100%, 200px); -} diff --git a/examples/ProgressLinear.status.css b/examples/ProgressLinear.status.css new file mode 100644 index 00000000000..8cc0a04ee6d --- /dev/null +++ b/examples/ProgressLinear.status.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: column; + gap: var(--iui-size-s); + width: min(100%, 200px); +} diff --git a/examples/ProgressLinear.status.jsx b/examples/ProgressLinear.status.jsx new file mode 100644 index 00000000000..5c17a122607 --- /dev/null +++ b/examples/ProgressLinear.status.jsx @@ -0,0 +1,28 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressLinear } from '@itwin/itwinui-react'; + +export default () => { + return ( +
+ + + +
+ ); +}; diff --git a/examples/ProgressRadial.content.jsx b/examples/ProgressRadial.content.jsx new file mode 100644 index 00000000000..60be209e581 --- /dev/null +++ b/examples/ProgressRadial.content.jsx @@ -0,0 +1,14 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressRadial, Text } from '@itwin/itwinui-react'; + +export default () => { + return ( + + 100% + + ); +}; diff --git a/examples/ProgressRadial.size.css b/examples/ProgressRadial.size.css new file mode 100644 index 00000000000..c63c46e5e74 --- /dev/null +++ b/examples/ProgressRadial.size.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: row; + align-items: center; + gap: var(--iui-size-s); +} diff --git a/examples/ProgressRadial.size.jsx b/examples/ProgressRadial.size.jsx new file mode 100644 index 00000000000..66d40154e77 --- /dev/null +++ b/examples/ProgressRadial.size.jsx @@ -0,0 +1,17 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressRadial } from '@itwin/itwinui-react'; + +export default () => { + return ( +
+ + + + +
+ ); +}; diff --git a/examples/ProgressRadial.status.css b/examples/ProgressRadial.status.css new file mode 100644 index 00000000000..c63c46e5e74 --- /dev/null +++ b/examples/ProgressRadial.status.css @@ -0,0 +1,6 @@ +.demo-container { + display: flex; + flex-direction: row; + align-items: center; + gap: var(--iui-size-s); +} diff --git a/examples/ProgressRadial.status.jsx b/examples/ProgressRadial.status.jsx new file mode 100644 index 00000000000..de528ea449b --- /dev/null +++ b/examples/ProgressRadial.status.jsx @@ -0,0 +1,16 @@ +/*--------------------------------------------------------------------------------------------- + * Copyright (c) Bentley Systems, Incorporated. All rights reserved. + * See LICENSE.md in the project root for license terms and full copyright notice. + *--------------------------------------------------------------------------------------------*/ +import * as React from 'react'; +import { ProgressRadial } from '@itwin/itwinui-react'; + +export default () => { + return ( +
+ + + +
+ ); +}; diff --git a/examples/ProgressRadial.main.jsx b/examples/ProgressRadial.value.jsx similarity index 91% rename from examples/ProgressRadial.main.jsx rename to examples/ProgressRadial.value.jsx index 5b2edd4aed9..bd9e16616ee 100644 --- a/examples/ProgressRadial.main.jsx +++ b/examples/ProgressRadial.value.jsx @@ -6,5 +6,5 @@ import * as React from 'react'; import { ProgressRadial } from '@itwin/itwinui-react'; export default () => { - return ; + return ; }; diff --git a/examples/index.tsx b/examples/index.tsx index d9871e09243..a479d84d6b0 100644 --- a/examples/index.tsx +++ b/examples/index.tsx @@ -900,17 +900,53 @@ export const PopoverFocusExample = withThemeProvider(PopoverFocusExampleRaw); // ---------------------------------------------------------------------------- -import { default as ProgressLinearMainExampleRaw } from './ProgressLinear.main'; -const ProgressLinearMainExample = withThemeProvider( - ProgressLinearMainExampleRaw, +import { default as ProgressIndicatorsMainExampleRaw } from './ProgressIndicators.main'; +const ProgressIndicatorsMainExample = withThemeProvider( + ProgressIndicatorsMainExampleRaw, ); -export { ProgressLinearMainExample }; +export { ProgressIndicatorsMainExample }; -import { default as ProgressRadialMainExampleRaw } from './ProgressRadial.main'; -const ProgressRadialMainExample = withThemeProvider( - ProgressRadialMainExampleRaw, +import { default as ProgressIndicatorsValueExampleRaw } from './ProgressIndicators.value'; +const ProgressIndicatorsValueExample = withThemeProvider( + ProgressIndicatorsValueExampleRaw, ); -export { ProgressRadialMainExample }; +export { ProgressIndicatorsValueExample }; + +import { default as ProgressLinearAnimatedExampleRaw } from './ProgressLinear.isAnimated'; +const ProgressLinearAnimatedExample = withThemeProvider( + ProgressLinearAnimatedExampleRaw, +); +export { ProgressLinearAnimatedExample }; + +import { default as ProgressLinearLabelExampleRaw } from './ProgressLinear.label'; +const ProgressLinearLabelExample = withThemeProvider( + ProgressLinearLabelExampleRaw, +); +export { ProgressLinearLabelExample }; + +import { default as ProgressLinearStatusExampleRaw } from './ProgressLinear.status'; +const ProgressLinearStatusExample = withThemeProvider( + ProgressLinearStatusExampleRaw, +); +export { ProgressLinearStatusExample }; + +import { default as ProgressRadialSizeExampleRaw } from './ProgressRadial.size'; +const ProgressRadialSizeExample = withThemeProvider( + ProgressRadialSizeExampleRaw, +); +export { ProgressRadialSizeExample }; + +import { default as ProgressRadialContentExampleRaw } from './ProgressRadial.content'; +const ProgressRadialContentExample = withThemeProvider( + ProgressRadialContentExampleRaw, +); +export { ProgressRadialContentExample }; + +import { default as ProgressRadialStatusExampleRaw } from './ProgressRadial.status'; +const ProgressRadialStatusExample = withThemeProvider( + ProgressRadialStatusExampleRaw, +); +export { ProgressRadialStatusExample }; // ----------------------------------------------------------------------------