From 85c9f25f2241bf39722b35335120888608cb8cd9 Mon Sep 17 00:00:00 2001 From: lilyvc <45168453+lilyvc@users.noreply.github.com> Date: Fri, 10 Nov 2023 16:34:05 +0000 Subject: [PATCH] Progress Site Docs (#2684) --- .../LinearProgress/LinearProgress.tsx | 3 +- site/docs/components/progress/examples.mdx | 12 +- site/docs/components/progress/index.mdx | 16 ++- site/docs/components/progress/usage.mdx | 29 +++-- site/src/examples/progress/Circular.tsx | 6 + site/src/examples/progress/Linear.tsx | 6 + site/src/examples/progress/WithMaxVal.tsx | 52 ++++++++ site/src/examples/progress/WithProgVal.tsx | 117 ++++++++++++++++++ site/src/examples/progress/index.ts | 4 + 9 files changed, 214 insertions(+), 31 deletions(-) create mode 100644 site/src/examples/progress/Circular.tsx create mode 100644 site/src/examples/progress/Linear.tsx create mode 100644 site/src/examples/progress/WithMaxVal.tsx create mode 100644 site/src/examples/progress/WithProgVal.tsx create mode 100644 site/src/examples/progress/index.ts diff --git a/packages/lab/src/progress/LinearProgress/LinearProgress.tsx b/packages/lab/src/progress/LinearProgress/LinearProgress.tsx index c9bcef2b175..ea3c3bfd730 100644 --- a/packages/lab/src/progress/LinearProgress/LinearProgress.tsx +++ b/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 { */ max?: number; /** + * The unit shown on the progress indicator. * Default unit is `%`. */ unit?: string; diff --git a/site/docs/components/progress/examples.mdx b/site/docs/components/progress/examples.mdx index 9cebb37f777..817e1684d68 100644 --- a/site/docs/components/progress/examples.mdx +++ b/site/docs/components/progress/examples.mdx @@ -11,7 +11,7 @@ data: - + ### Circular progress @@ -19,7 +19,7 @@ Use linear or circular depending on the context, layout and functionality of an - + ### Linear progress @@ -27,7 +27,7 @@ Use linear or circular depending on the context, layout and functionality of an - + ### With maximum value @@ -35,12 +35,12 @@ Specify the maximum value of the progress indicator. The percentage progress wil - + ### With progressing value - +Dynamically represent a progressing value in the progress indicator. -{/* Add more ... blocks here as needed */} + diff --git a/site/docs/components/progress/index.mdx b/site/docs/components/progress/index.mdx index aa9fa9ec374..a4524e1e88e 100644 --- a/site/docs/components/progress/index.mdx +++ b/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 */} diff --git a/site/docs/components/progress/usage.mdx b/site/docs/components/progress/usage.mdx index d1f88a62bfa..c42d7a3a7ad 100644 --- a/site/docs/components/progress/usage.mdx +++ b/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` - + -#### Linear Progress +#### `LinearProgress` - + diff --git a/site/src/examples/progress/Circular.tsx b/site/src/examples/progress/Circular.tsx new file mode 100644 index 00000000000..5823d7c0d35 --- /dev/null +++ b/site/src/examples/progress/Circular.tsx @@ -0,0 +1,6 @@ +import { ReactElement } from "react"; +import { CircularProgress } from "@salt-ds/lab"; + +export const Circular = (): ReactElement => ( + +); diff --git a/site/src/examples/progress/Linear.tsx b/site/src/examples/progress/Linear.tsx new file mode 100644 index 00000000000..e09d60a8020 --- /dev/null +++ b/site/src/examples/progress/Linear.tsx @@ -0,0 +1,6 @@ +import { ReactElement } from "react"; +import { LinearProgress } from "@salt-ds/lab"; + +export const Linear = (): ReactElement => ( + +); diff --git a/site/src/examples/progress/WithMaxVal.tsx b/site/src/examples/progress/WithMaxVal.tsx new file mode 100644 index 00000000000..c8aa4ac5b54 --- /dev/null +++ b/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 ( + +

max = 500, value = 250

+ + + + setSelectedType("circular")} + /> + setSelectedType("linear")} + /> + + + + + + {selectedType === "circular" && ( + + )} + {selectedType === "linear" && ( + + )} + + + ); +}; diff --git a/site/src/examples/progress/WithProgVal.tsx b/site/src/examples/progress/WithProgVal.tsx new file mode 100644 index 00000000000..a5479fe082e --- /dev/null +++ b/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 ( + + + + + + + + + + + + + setSelectedType("circular")} + /> + setSelectedType("linear")} + /> + + + + + + {selectedType === "circular" && ( + + )} + {selectedType === "linear" && ( + + )} + + + ); +}; diff --git a/site/src/examples/progress/index.ts b/site/src/examples/progress/index.ts new file mode 100644 index 00000000000..f0fb2867d57 --- /dev/null +++ b/site/src/examples/progress/index.ts @@ -0,0 +1,4 @@ +export * from "./Circular"; +export * from "./Linear"; +export * from "./WithMaxVal"; +export * from "./WithProgVal";