Updated documentation for Progress Indicators (#2271)

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
 ---
 
 <p>{frontmatter.description}</p>
 
-## Progress linear
+## Usage
 
-<Placeholder componentPageName='progresslinear--determinate' />
+There are two types of progress indicators available as separate components:
 
-<LiveExample src='ProgressLinear.main.jsx' truncate={false}>
-  <AllExamples.ProgressLinearMainExample client:load />
+- `ProgressLinear`: shows progress on a linear bar.
+- `ProgressRadial`: shows progress in a circular form.
+
+<LiveExample src='ProgressIndicators.main.jsx' truncate={false}>
+  <AllExamples.ProgressIndicatorsMainExample client:load />
 </LiveExample>
 
-### 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.
 
-<PropsTable path='@itwin/itwinui-react/esm/core/ProgressIndicators/ProgressLinear.d.ts' />
+### 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.
 
-<Placeholder componentPageName='progressradial--determinate' />
+<LiveExample src='ProgressIndicators.value.jsx' truncate={false}>
+  <AllExamples.ProgressIndicatorsValueExample client:load />
+</LiveExample>
 
-<LiveExample src='ProgressRadial.main.jsx' truncate={false}>
-  <AllExamples.ProgressRadialMainExample client:load />
+Exclusively for `ProgressLinear`, the `isAnimated` flag is helpful when applying animation to the indicator as the value changes.
+
+<LiveExample src='ProgressLinear.isAnimated.jsx'>
+  <AllExamples.ProgressLinearAnimatedExample client:load />
 </LiveExample>
 
+**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.
+
+<LiveExample src='ProgressLinear.status.jsx'>
+  <AllExamples.ProgressLinearStatusExample client:load />
+</LiveExample>
+
+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.
+
+<LiveExample src='ProgressRadial.status.jsx'>
+  <AllExamples.ProgressRadialStatusExample client:load />
+</LiveExample>
+
+### 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`.
+
+<LiveExample src='ProgressLinear.label.jsx'>
+  <AllExamples.ProgressLinearLabelExample client:load />
+</LiveExample>
+
+### Size
+
+Four `size` options available are:
+
+- `"x-small"`
+- `"small"`
+- `"medium"` (default)
+- `"large"`
+
+This prop is only available for `ProgressRadial`.
+
+<LiveExample src='ProgressRadial.size.jsx'>
+  <AllExamples.ProgressRadialSizeExample client:load />
+</LiveExample>
+
+### 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`.
+
+<LiveExample src='ProgressRadial.content.jsx'>
+  <AllExamples.ProgressRadialContentExample client:load />
+</LiveExample>
+
+**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
+
+<PropsTable path='@itwin/itwinui-react/esm/core/ProgressIndicators/ProgressLinear.d.ts' />
+
+### ProgressRadial
 
 <PropsTable path='@itwin/itwinui-react/esm/core/ProgressIndicators/ProgressRadial.d.ts' />

examples/ProgressIndicators.main.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  width: 200px;
+  gap: var(--iui-size-s);
+}

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 (
+    <div className='demo-container'>
+      <ProgressLinear />
+      <ProgressRadial />
+    </div>
+  );
+};

examples/ProgressIndicators.value.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  width: 200px;
+  gap: var(--iui-size-s);
+}

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 (
+    <div className='demo-container'>
+      <ProgressLinear value={20} />
+      <ProgressRadial value={50} />
+    </div>
+  );
+};

examples/ProgressLinear.isAnimated.css

@@ -0,0 +1,6 @@
+.demo-container {
+  width: 200px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--iui-size-xs);
+}

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 (
+    <div className='demo-container'>
+      <ProgressLinear
+        value={value}
+        isAnimated={!isDone}
+        labels={!isDone ? ['Loading...', `${value}%`] : ['Upload succeeded.']}
+        status={isDone ? 'positive' : undefined}
+        key={isDone.toString()}
+      />
+      <Button onClick={() => setValue(0)}>Reset process</Button>
+    </div>
+  );
+};

examples/ProgressLinear.label.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--iui-size-s);
+  width: min(100%, 200px);
+}

examples/ProgressLinear.main.jsx → examples/ProgressLinear.label.jsx

@@ -8,7 +8,8 @@ import { ProgressLinear } from '@itwin/itwinui-react';
 export default () => {
   return (
     <div className='demo-container'>
-      <ProgressLinear indeterminate />
+      <ProgressLinear value={50} labels={['Centered Label']} />
+      <ProgressLinear value={50} labels={['Loading...', '50%']} />
     </div>
   );
 };

examples/ProgressLinear.status.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: column;
+  gap: var(--iui-size-s);
+  width: min(100%, 200px);
+}

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 (
+    <div className='demo-container'>
+      <ProgressLinear
+        value={100}
+        labels={['Upload succeeded!']}
+        status='positive'
+      />
+      <ProgressLinear
+        value={50}
+        labels={['Upload failed.', '50%']}
+        status='negative'
+      />
+      <ProgressLinear
+        value={75}
+        labels={['Attention required.', '75%']}
+        status='warning'
+      />
+    </div>
+  );
+};

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 (
+    <ProgressRadial value={100} status='positive' size='large'>
+      <Text variant='small'>100%</Text>
+    </ProgressRadial>
+  );
+};

examples/ProgressRadial.size.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--iui-size-s);
+}

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 (
+    <div className='demo-container'>
+      <ProgressRadial size='x-small' />
+      <ProgressRadial size='small' />
+      <ProgressRadial />
+      <ProgressRadial size='large' />
+    </div>
+  );
+};

examples/ProgressRadial.status.css

@@ -0,0 +1,6 @@
+.demo-container {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--iui-size-s);
+}

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 (
+    <div className='demo-container'>
+      <ProgressRadial value={100} status='positive' />
+      <ProgressRadial value={50} status='negative' />
+      <ProgressRadial value={75} status='warning' />
+    </div>
+  );
+};

examples/ProgressRadial.main.jsx → examples/ProgressRadial.value.jsx

@@ -6,5 +6,5 @@ import * as React from 'react';
 import { ProgressRadial } from '@itwin/itwinui-react';
 
 export default () => {
-  return <ProgressRadial indeterminate />;
+  return <ProgressRadial value={50} />;
 };

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 };
 
 // ----------------------------------------------------------------------------