Progress Site Docs (#2684)

packages/lab/src/progress/LinearProgress/LinearProgress.tsx

@@ -1,4 +1,4 @@
-import { CSSProperties, forwardRef, HTMLAttributes, ReactNode } from "react";
+import { CSSProperties, forwardRef, HTMLAttributes } from "react";
 import { clsx } from "clsx";
 import { makePrefixer } from "@salt-ds/core";
 
@@ -21,6 +21,7 @@ export interface LinearProgressProps extends HTMLAttributes<HTMLDivElement> {
    */
   max?: number;
   /**
+   * The unit shown on the progress indicator.
    * Default unit is `%`.
    */
   unit?: string;

site/docs/components/progress/examples.mdx

@@ -11,36 +11,36 @@ data:
 
 <LivePreviewControls>
 
-<LivePreview componentName="component-name" exampleName="ComponentExample" displayName="Circular progress">
+<LivePreview componentName="progress" exampleName="Circular" displayName="Circular progress">
 
 ### Circular progress
 
 Use linear or circular depending on the context, layout and functionality of an application. Use the same indicator for the same type of process to ensure consistency.
 
 </LivePreview>
 
-<LivePreview componentName="component-name" exampleName="ComponentExample" displayName="Linear progress">
+<LivePreview componentName="progress" exampleName="Linear" displayName="Linear progress">
 
 ### Linear progress
 
 Use linear or circular depending on the context, layout and functionality of an application. Use the same indicator for the same type of process to ensure consistency.
 
 </LivePreview>
 
-<LivePreview componentName="component-name" exampleName="ComponentExample" displayName="With maximum value">
+<LivePreview componentName="progress" exampleName="WithMaxVal" displayName="With maximum value">
 
 ### With maximum value
 
 Specify the maximum value of the progress indicator. The percentage progress will be calculated using this value. Default value is 100.
 
 </LivePreview>
 
-<LivePreview componentName="component-name" exampleName="ComponentExample" displayName="With progressing value">
+<LivePreview componentName="progress" exampleName="WithProgVal" displayName="With progressing value">
 
 ### With progressing value
 
-</LivePreview>
+Dynamically represent a progressing value in the progress indicator.
 
-{/* Add more <LivePreview>...</LivePreview> blocks here as needed */}
+</LivePreview>
 
 </LivePreviewControls>

site/docs/components/progress/index.mdx

@@ -1,23 +1,21 @@
 ---
 title: Progress
+sidebar:
+  label: Progress 🚧
 data:
-  description: "A progress indicator gives the user an understanding of how long a system operation will take. It should be used when the operation will take more than a second to complete. Two variants are available to accommodate different layout constraints: linear and circular."
+  description: "Circular Progress and Linear Progress communicate the status of an ongoing operation, such as file downloads or data uploads. The two components accommodate different layout constraints."
 
   # Fill in the info from the content template's "Metadata" table below.
   # To omit optional items, comment them out with #
-  sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/core/src/progress"
+  sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/lab/src/progress"
   package:
-    name: "@salt-ds/core"
-  alsoKnownAs: []
+    name: "@salt-ds/lab"
+  alsoKnownAs: [Progress Bar, Progress Indicator]
   relatedComponents: []
   # stickerSheet: "https://figma.com/..."
-
+  status: Lab component
 # Leave this as is
 layout: DetailComponent
-
-# TODO: Remove this once the docs are ready
-sidebar:
-  exclude: true
 ---
 
 {/* This area stays blank */}

site/docs/components/progress/usage.mdx

@@ -9,35 +9,34 @@ data:
   $ref: ./#/data
 ---
 
-### Using the Progress component
+### Using the Progress components
 
-It should be used when the operation will take more than a second to complete, to reassure users that the operation is in progress.
+#### When to use Progress
+
+- When it’s possible to determine the length of time remaining for a task or operation to complete. This will reassure the user that it is being processed.
+- To provide users with a visual indication of the status of an operation, or how much of a process is completed.
 
 #### When not to use Progress
 
-Do not use when an operation takes a short amount of time, as it may be confusing and distracting for users.
+- When a task or operation will take an indeterminate length of time to complete. Instead, use [`Spinner`](/salt/components/spinner).
+- To indicate the loading of content on navigation. Instead, use [`Spinner`](/salt/components/spinner).
 
 ### Import
 
-{/* Update the text and code snippet below as needed: */}
-
-To import the Progress components from the core Salt package, use:
+To import the `CircularProgress` and `LinearProgress` components from the lab Salt package, use:
 
 ```js
-import { CircularProgress } from "@salt-ds/core";
+import { CircularProgress } from "@salt-ds/lab";
 // or
-import { LinearProgress } from "@salt-ds/core";
+import { LinearProgress } from "@salt-ds/lab";
 ```
 
 ### Props
 
-{/* Update packageName and componentName below as needed */}
-{/* packageName is optional and defaults to "core" if omitted */}
-
-#### Circular Progress
+#### `CircularProgress`
 
-<PropsTable packageName="core" componentName="CircularProgress" />
+<PropsTable packageName="lab" componentName="CircularProgress" />
 
-#### Linear Progress
+#### `LinearProgress`
 
-<PropsTable packageName="core" componentName="LinearProgress" />
+<PropsTable packageName="lab" componentName="LinearProgress" />

site/src/examples/progress/Circular.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { CircularProgress } from "@salt-ds/lab";
+
+export const Circular = (): ReactElement => (
+  <CircularProgress aria-label="Download" value={38} />
+);

site/src/examples/progress/Linear.tsx

@@ -0,0 +1,6 @@
+import { ReactElement } from "react";
+import { LinearProgress } from "@salt-ds/lab";
+
+export const Linear = (): ReactElement => (
+  <LinearProgress aria-label="Download" value={38} />
+);

site/src/examples/progress/WithMaxVal.tsx

@@ -0,0 +1,52 @@
+import { ReactElement, useState } from "react";
+import { CircularProgress, LinearProgress } from "@salt-ds/lab";
+import {
+  FlexItem,
+  FlexLayout,
+  FlowLayout,
+  RadioButton,
+  RadioButtonGroup,
+} from "@salt-ds/core";
+
+export const WithMaxVal = (): ReactElement => {
+  const [selectedType, setSelectedType] = useState("circular");
+
+  return (
+    <FlexLayout direction="column" style={{ height: "100%" }}>
+      <h3 style={{ textAlign: "center" }}> max = 500, value = 250</h3>
+      <FlexItem>
+        <FlowLayout justify="center" className="controls" gap={1}>
+          <RadioButtonGroup direction="horizontal" defaultChecked>
+            <RadioButton
+              key="circular"
+              label="Circular"
+              value="circular"
+              checked
+              onChange={() => setSelectedType("circular")}
+            />
+            <RadioButton
+              key="linear"
+              label="Linear"
+              value="linear"
+              onChange={() => setSelectedType("linear")}
+            />
+          </RadioButtonGroup>
+        </FlowLayout>
+      </FlexItem>
+
+      <FlexItem align="center" grow={1}>
+        {selectedType === "circular" && (
+          <CircularProgress aria-label="Download" value={250} max={500} />
+        )}
+        {selectedType === "linear" && (
+          <LinearProgress
+            aria-label="Download"
+            value={250}
+            max={500}
+            style={{ height: "100%" }}
+          />
+        )}
+      </FlexItem>
+    </FlexLayout>
+  );
+};

site/src/examples/progress/WithProgVal.tsx

@@ -0,0 +1,117 @@
+import { ReactElement, useState, useEffect, useCallback } from "react";
+import { CircularProgress, LinearProgress } from "@salt-ds/lab";
+import {
+  Button,
+  FlexItem,
+  FlexLayout,
+  FlowLayout,
+  RadioButton,
+  RadioButtonGroup,
+} from "@salt-ds/core";
+
+function useProgressingValue(updateInterval = 100) {
+  const [value, setValue] = useState(0);
+  const [isProgressing, setIsProgressing] = useState(false);
+
+  const handleStop = useCallback(() => {
+    if (isProgressing) {
+      setIsProgressing(false);
+    }
+  }, [isProgressing]);
+
+  const handleStart = () => {
+    if (!isProgressing) {
+      setIsProgressing(true);
+    }
+  };
+
+  const handleReset = () => {
+    setValue(0);
+    handleStop();
+  };
+
+  useEffect(() => {
+    if (isProgressing) {
+      const id = setInterval(() => {
+        setValue((preValue) => preValue + 1);
+      }, updateInterval);
+
+      return () => {
+        clearInterval(id);
+      };
+    }
+    return;
+  }, [isProgressing, updateInterval]);
+
+  useEffect(
+    function stopWhenComplete() {
+      if (value === 100) {
+        handleStop();
+      }
+    },
+    [handleStop, value]
+  );
+
+  return {
+    handleReset,
+    handleStart,
+    handleStop,
+    isProgressing,
+    value,
+  };
+}
+
+export const WithProgVal = (): ReactElement => {
+  const { handleReset, handleStart, handleStop, isProgressing, value } =
+    useProgressingValue();
+  const [selectedType, setSelectedType] = useState("circular");
+
+  return (
+    <FlexLayout direction="column" style={{ height: "100%" }}>
+      <FlexItem>
+        <FlowLayout justify="center" className="controls" gap={1}>
+          <Button disabled={isProgressing} onClick={handleStart}>
+            Start
+          </Button>
+          <Button disabled={!isProgressing} onClick={handleStop}>
+            Stop
+          </Button>
+          <Button onClick={handleReset}>Reset</Button>
+        </FlowLayout>
+      </FlexItem>
+
+      <FlexItem>
+        <FlowLayout justify="center" className="controls" gap={1}>
+          <RadioButtonGroup direction="horizontal" defaultChecked>
+            <RadioButton
+              key="circular"
+              label="Circular"
+              value="circular"
+              checked
+              onChange={() => setSelectedType("circular")}
+            />
+            <RadioButton
+              key="linear"
+              label="Linear"
+              value="linear"
+              onChange={() => setSelectedType("linear")}
+            />
+          </RadioButtonGroup>
+        </FlowLayout>
+      </FlexItem>
+
+      <FlexItem align="center" grow={1}>
+        {selectedType === "circular" && (
+          <CircularProgress aria-label="Download" value={value} />
+        )}
+        {selectedType === "linear" && (
+          <LinearProgress
+            aria-label="Download"
+            value={value}
+            style={{ height: "100%" }}
+          />
+        )}
+      </FlexItem>
+    </FlexLayout>
+  );
+};

site/src/examples/progress/index.ts

@@ -0,0 +1,4 @@
+export * from "./Circular";
+export * from "./Linear";
+export * from "./WithMaxVal";
+export * from "./WithProgVal";