@nypl/design-system-react-components 0.25.1 → 0.25.5

package/src/components/ProgressIndicator/ProgressIndicator.stories.mdx

@@ -0,0 +1,292 @@
+import {
+  Meta,
+  Story,
+  ArgsTable,
+  Canvas,
+  Description,
+} from "@storybook/addon-docs/blocks";
+import { withDesign } from "storybook-addon-designs";
+import { Box } from "@chakra-ui/react";
+
+import ProgressIndicator from "./ProgressIndicator";
+import {
+  ProgressIndicatorSizes,
+  ProgressIndicatorTypes,
+} from "./ProgressIndicatorTypes";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { GridGaps } from "../Grid/GridTypes";
+
+<Meta
+  title={getCategory("ProgressIndicator")}
+  component={ProgressIndicator}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url:
+        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=37638%3A23842",
+    },
+    jest: ["ProgressIndicator.test.tsx"],
+  }}
+  argTypes={{
+    id: { table: { disable: true } },
+  }}
+/>
+
+# ProgressIndicator
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.4`   |
+| Latest            | `0.25.4`   |
+
+<Description of={ProgressIndicator} />
+
+<Canvas withToolbar>
+  <Story
+    name="Basic with props"
+    args={{
+      darkMode: false,
+      indicatorType: ProgressIndicatorTypes.Linear,
+      isIndeterminate: false,
+      labelText: "Progress",
+      showLabel: true,
+      size: ProgressIndicatorSizes.Default,
+      value: 50,
+    }}
+  >
+    {(args) => <ProgressIndicator {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Basic with props" />
+
+## Linear Type
+
+Progress bars are preferred in vertically narrow areas such as tables, cards,
+dialogs, etc.
+
+<Canvas>
+  <Story
+    name="Linear Type"
+    args={{
+      darkMode: false,
+      indicatorType: ProgressIndicatorTypes.Linear,
+      isIndeterminate: false,
+      labelText: "Linear Progress Type",
+      showLabel: true,
+      size: ProgressIndicatorSizes.Default,
+      value: 50,
+    }}
+    argTypes={{
+      indicatorType: { table: { disable: true } },
+    }}
+  >
+    {(args) => <ProgressIndicator {...args} />}
+  </Story>
+</Canvas>
+
+## Circular Type
+
+The circular progress type is preferred for large content areas and for
+full-screen loading. Set the `indicatorType` prop to
+`ProgressIndicatorTypes.Circular` for this type.
+
+<Canvas>
+  <Story
+    name="Circular Type"
+    args={{
+      darkMode: false,
+      indicatorType: ProgressIndicatorTypes.Circular,
+      isIndeterminate: false,
+      labelText: "Circular Progress Type",
+      showLabel: true,
+      size: ProgressIndicatorSizes.Default,
+      value: 50,
+    }}
+    argTypes={{
+      indicatorType: { table: { disable: true } },
+    }}
+  >
+    {(args) => <ProgressIndicator {...args} />}
+  </Story>
+</Canvas>
+
+### Sizing
+
+The starting height for the progress bar is 4px on mobile and 8px for desktop.
+The `size` prop can be used to optionally set the height to 4px for desktop
+through the `ProgressIndicatorSizes.Small` value.
+
+`size={ProgressIndicatorSizes.Small}`
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator labelText="Default 8px size" value={50} />
+      <ProgressIndicator
+        labelText="Small 4px size"
+        size={ProgressIndicatorSizes.Small}
+        value={50}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+The starting size for the circular progress is 48px and can be made smaller to
+24px with the `size` prop. The small 24px size can be used for inline local
+changes in content. Note that in the small size, the label text and the
+percentage will not displayed.
+
+`size={ProgressIndicatorSizes.Small}`
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator
+        labelText="Default 48px size"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        value={50}
+      />
+      <ProgressIndicator
+        labelText="Small 24px size"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        size={ProgressIndicatorSizes.Small}
+        value={50}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+### Labels
+
+The `labelText` value and the `value` percentage are displayed by default. They
+can be hidden through the `showLabel` prop.
+
+`showLabel={false}`
+
+Accessibility Note: when `showLabel` is false, the `aria-label` prop is set in
+the progress element to provide a description of the progress for screen readers.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator
+        labelText="This label will be added through aria-label"
+        value={50}
+        showLabel={false}
+      />
+      <ProgressIndicator
+        labelText="This label will be added through aria-label"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        value={50}
+        showLabel={false}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+### Indeterminate State
+
+When the `isIndeterminate` prop is set to true, the `value` prop is ignored and
+the state is set to an animated indeterminate state. This is often used when the
+exact value or progress of the task is unknown.
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator
+        labelText="Indeterminate state"
+        isIndeterminate
+        value={50}
+      />
+      <ProgressIndicator
+        labelText="Indeterminate state"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        isIndeterminate
+        value={50}
+      />
+    </SimpleGrid>
+  </DSProvider>
+</Canvas>
+
+### Dark Mode
+
+When in "dark mode", set the `darkMode` prop to true. This will render the
+progress bar and the label text in white for better contrast.
+
+Note: the background is manually set to better showcase the `darkMode` prop.
+
+<Canvas>
+  <DSProvider>
+    <Box bg="black" w="100%" h="200px" p="20px">
+      <SimpleGrid columns={1} gap={GridGaps.Medium}>
+        <ProgressIndicator labelText="Dark Mode" value={50} darkMode />
+        <ProgressIndicator
+          labelText="Dark Mode"
+          indicatorType={ProgressIndicatorTypes.Circular}
+          value={50}
+          darkMode
+        />
+      </SimpleGrid>
+    </Box>
+  </DSProvider>
+</Canvas>
+
+### Example
+
+In the following example, we are setting the `value` prop based on a timer that
+increases the value every second by 10. Once it reaches 100, it resets to 0.
+This is a very simple example using `React.useState` to manage the state but in
+a real application the value would come from a data source or server.
+
+```tsx
+// Example code
+function ProgressIndicatorExample() {
+  const [value, setValue] = React.useState(0);
+  React.useEffect(() => {
+    const interval = setInterval(() => {
+      setValue((value) => (value === 100 ? 0 : value + 10));
+    }, 1000);
+    return () => clearInterval(interval);
+  }, []);
+  return (
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator labelText="Progress example" value={value} />
+      <ProgressIndicator
+        labelText="Progress example"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        value={value}
+      />
+    </SimpleGrid>
+  );
+}
+```
+
+export function ProgressIndicatorExample() {
+  const [value, setValue] = React.useState(0);
+  React.useEffect(() => {
+    const interval = setInterval(() => {
+      setValue((value) => (value === 100 ? 0 : value + 10));
+    }, 1000);
+    return () => clearInterval(interval);
+  }, []);
+  return (
+    <SimpleGrid columns={1} gap={GridGaps.Medium}>
+      <ProgressIndicator labelText="Progress example" value={value} />
+      <ProgressIndicator
+        labelText="Progress example"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        value={value}
+      />
+    </SimpleGrid>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <ProgressIndicatorExample />
+  </DSProvider>
+</Canvas>

package/src/components/ProgressIndicator/ProgressIndicator.test.tsx

@@ -0,0 +1,225 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import ProgressIndicator from "./ProgressIndicator";
+import { ProgressIndicatorTypes } from "./ProgressIndicatorTypes";
+
+describe("ProgressIndicator Accessibility", () => {
+  it("passes axe accessibility for linear and circular types", async () => {
+    const linearUtils = render(
+      <ProgressIndicator labelText="Linear" value={50} />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        labelText="Circular"
+        value={50}
+        indicatorType={ProgressIndicatorTypes.Circular}
+      />
+    );
+    expect(await axe(linearUtils.container)).toHaveNoViolations();
+    expect(await axe(circularUtils.container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility for linear and circular types without labels", async () => {
+    const linearUtils = render(
+      <ProgressIndicator labelText="Linear" value={50} showLabel={false} />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        labelText="Circular"
+        value={50}
+        indicatorType={ProgressIndicatorTypes.Circular}
+        showLabel={false}
+      />
+    );
+    expect(await axe(linearUtils.container)).toHaveNoViolations();
+    expect(await axe(circularUtils.container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility for linear and circular types for indeterminate state", async () => {
+    const linearUtils = render(
+      <ProgressIndicator labelText="Linear" value={50} isIndeterminate />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        labelText="Circular"
+        value={50}
+        indicatorType={ProgressIndicatorTypes.Circular}
+        isIndeterminate
+      />
+    );
+    expect(await axe(linearUtils.container)).toHaveNoViolations();
+    expect(await axe(circularUtils.container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility for linear and circular types for dark mode", async () => {
+    const linearUtils = render(
+      <ProgressIndicator labelText="Linear" value={50} darkMode />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        labelText="Circular"
+        value={50}
+        indicatorType={ProgressIndicatorTypes.Circular}
+        darkMode
+      />
+    );
+    expect(await axe(linearUtils.container)).toHaveNoViolations();
+    expect(await axe(circularUtils.container)).toHaveNoViolations();
+  });
+});
+
+describe("ProgressIndicator", () => {
+  it("renders a label and a progressbar for the linear type", () => {
+    render(<ProgressIndicator labelText="Linear" value={50} />);
+    expect(screen.getByLabelText("Linear")).toBeInTheDocument();
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+  });
+
+  it("renders a label, a progressbar, and an svg for the circular type", () => {
+    const { container } = render(
+      <ProgressIndicator
+        labelText="Circular"
+        indicatorType={ProgressIndicatorTypes.Circular}
+        value={50}
+      />
+    );
+    expect(screen.getByLabelText("Circular")).toBeInTheDocument();
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+    expect(container.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("renders the appropriate aria atttribute when the label is hidden", () => {
+    render(
+      <ProgressIndicator labelText="Linear" value={50} showLabel={false} />
+    );
+    expect(screen.getByLabelText("Linear")).toBeInTheDocument();
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-label",
+      "Linear"
+    );
+  });
+
+  it("renders the value passed", () => {
+    const { rerender } = render(
+      <ProgressIndicator labelText="Linear" value={50} />
+    );
+    expect(screen.getByText("50%")).toBeInTheDocument();
+
+    rerender(<ProgressIndicator labelText="Linear" value={89} />);
+    expect(screen.getByText("89%")).toBeInTheDocument();
+
+    rerender(<ProgressIndicator labelText="Linear" value={4} />);
+    expect(screen.getByText("4%")).toBeInTheDocument();
+  });
+
+  it("logs a warning if a value less than 0 is passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<ProgressIndicator labelText="Linear" value={-20} />);
+
+    expect(warn).toHaveBeenCalledWith(
+      "ProgressIndicator: pass in a `value` between 0 and 100. Defaulting to 0."
+    );
+  });
+
+  it("logs a warning if a value more than 100 is passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(<ProgressIndicator labelText="Linear" value={150} />);
+
+    expect(warn).toHaveBeenCalledWith(
+      "ProgressIndicator: pass in a `value` between 0 and 100. Defaulting to 0."
+    );
+  });
+
+  it("Renders the UI snapshot correctly", () => {
+    const linearBasic = renderer
+      .create(
+        <ProgressIndicator id="linearBasic" labelText="Linear" value={50} />
+      )
+      .toJSON();
+    const circularBasic = renderer
+      .create(
+        <ProgressIndicator
+          id="circularBasic"
+          labelText="Circular"
+          value={50}
+          indicatorType={ProgressIndicatorTypes.Circular}
+        />
+      )
+      .toJSON();
+    const linearNoLabel = renderer
+      .create(
+        <ProgressIndicator
+          id="linearNoLabel"
+          labelText="Linear"
+          value={50}
+          showLabel={false}
+        />
+      )
+      .toJSON();
+    const circularNoLabel = renderer
+      .create(
+        <ProgressIndicator
+          id="circularNoLabel"
+          labelText="Circular"
+          value={50}
+          indicatorType={ProgressIndicatorTypes.Circular}
+          showLabel={false}
+        />
+      )
+      .toJSON();
+    const linearIndeterminate = renderer
+      .create(
+        <ProgressIndicator
+          id="linearIndeterminate"
+          labelText="Linear"
+          value={50}
+          isIndeterminate
+        />
+      )
+      .toJSON();
+    const circularIndeterminate = renderer
+      .create(
+        <ProgressIndicator
+          id="circularIndeterminate"
+          labelText="Circular"
+          value={50}
+          indicatorType={ProgressIndicatorTypes.Circular}
+          isIndeterminate
+        />
+      )
+      .toJSON();
+    const linearDarkMode = renderer
+      .create(
+        <ProgressIndicator
+          id="linearDarkMode"
+          labelText="Linear"
+          value={50}
+          darkMode
+        />
+      )
+      .toJSON();
+    const circularDarkMode = renderer
+      .create(
+        <ProgressIndicator
+          id="circularDarkMode"
+          labelText="Circular"
+          value={50}
+          indicatorType={ProgressIndicatorTypes.Circular}
+          darkMode
+        />
+      )
+      .toJSON();
+
+    expect(linearBasic).toMatchSnapshot();
+    expect(circularBasic).toMatchSnapshot();
+    expect(linearNoLabel).toMatchSnapshot();
+    expect(circularNoLabel).toMatchSnapshot();
+    expect(linearIndeterminate).toMatchSnapshot();
+    expect(circularIndeterminate).toMatchSnapshot();
+    expect(linearDarkMode).toMatchSnapshot();
+    expect(circularDarkMode).toMatchSnapshot();
+  });
+});

package/src/components/ProgressIndicator/ProgressIndicator.tsx

@@ -0,0 +1,126 @@
+import React from "react";
+import {
+  Box,
+  CircularProgress as ChakraCircularProgress,
+  CircularProgressLabel as ChakraCircularProgressLabel,
+  Progress as ChakraProgress,
+  useMultiStyleConfig,
+} from "@chakra-ui/react";
+
+import {
+  ProgressIndicatorSizes,
+  ProgressIndicatorTypes,
+} from "./ProgressIndicatorTypes";
+import generateUUID from "../../helpers/generateUUID";
+import Label from "../Label/Label";
+
+export interface ProgressIndicatorProps {
+  /** Flag to render the component in a dark background. */
+  darkMode?: boolean;
+  /** ID that other components can cross reference for accessibility purposes. */
+  id?: string;
+  /** Whether the `ProgressIndicator` should be linear or circular. */
+  indicatorType?: ProgressIndicatorTypes;
+  /** Whether the progress animation should display because the `value` prop is
+   * not known. When this is set to `true`, the `value` prop will be ignored. */
+  isIndeterminate?: boolean;
+  /** The text to display in an HTML `label` element. */
+  labelText: string;
+  /** Visually show or hide the label text. When set to `false`, then the label
+   * text will be added to the parent component as its `aria-label` attribute. */
+  showLabel?: boolean;
+  /** The size of the linear or circular progress. */
+  size?: ProgressIndicatorSizes;
+  /** A number between 0 to 100 that defines the progress' value. */
+  value?: number;
+}
+
+/**
+ * A component that displays a progress status for any task that takes a long
+ * time to complete or consists of multiple steps. Examples include downloading,
+ * uploading, or processing.
+ */
+const ProgressIndicator: React.FC<ProgressIndicatorProps> = (
+  props: ProgressIndicatorProps
+) => {
+  const {
+    darkMode = false,
+    id = generateUUID(),
+    indicatorType = ProgressIndicatorTypes.Linear,
+    isIndeterminate = false,
+    labelText,
+    showLabel = true,
+    size = ProgressIndicatorSizes.Default,
+    value = 0,
+  } = props;
+  const styles = useMultiStyleConfig("ProgressIndicator", {
+    darkMode,
+    size,
+  });
+  let finalValue = value;
+  if (finalValue < 0 || finalValue > 100) {
+    console.warn(
+      "ProgressIndicator: pass in a `value` between 0 and 100. Defaulting to 0."
+    );
+    finalValue = 0;
+  }
+  const progressProps = {
+    id,
+    // If the label is visually shown, associate it with the progress indicator.
+    // Otherwise, the `aria-label` will be added.
+    "aria-label": showLabel ? null : labelText,
+    "aria-labelledby": showLabel ? `${id}-label` : null,
+    // If `isIndeterminate` is true, then it overrides the `value` prop.
+    isIndeterminate: isIndeterminate || null,
+    value: isIndeterminate ? null : finalValue,
+  };
+  const progressComponent = (indicatorType) => {
+    // Only display the percentage text for the default size, not in the
+    // indeterminate state, and when `showLabel` is true.
+    if (indicatorType === ProgressIndicatorTypes.Circular) {
+      // For the small size, since the label won't be visible, we need to add
+      // it to the parent component's `aria-label` attribute.
+      if (size === ProgressIndicatorSizes.Small) {
+        progressProps["aria-label"] = labelText;
+      }
+      return (
+        <Box __css={styles.circularContainer}>
+          <ChakraCircularProgress {...progressProps} sx={styles.circular}>
+            {showLabel &&
+              !isIndeterminate &&
+              size !== ProgressIndicatorSizes.Small && (
+                <ChakraCircularProgressLabel>
+                  {finalValue}%
+                </ChakraCircularProgressLabel>
+              )}
+          </ChakraCircularProgress>
+          {showLabel && size !== ProgressIndicatorSizes.Small && (
+            <Label id={`${id}-label`} htmlFor={id}>
+              {labelText}
+            </Label>
+          )}
+        </Box>
+      );
+    }
+    // The Linear progress indicator is the default.
+    return (
+      <>
+        {showLabel && (
+          <Label id={`${id}-label`} htmlFor={id}>
+            {labelText}
+          </Label>
+        )}
+        <Box __css={styles.linearContainer}>
+          <ChakraProgress {...progressProps} sx={styles.linear} />
+          {showLabel && !isIndeterminate && (
+            <Box __css={styles.linearPercentage}>{finalValue}%</Box>
+          )}
+        </Box>
+      </>
+    );
+  };
+
+  return <Box __css={styles}>{progressComponent(indicatorType)}</Box>;
+};
+
+export default ProgressIndicator;

package/src/components/ProgressIndicator/ProgressIndicatorTypes.ts

@@ -0,0 +1,8 @@
+export enum ProgressIndicatorSizes {
+  Default = "default",
+  Small = "small",
+}
+export enum ProgressIndicatorTypes {
+  Circular = "circular",
+  Linear = "linear",
+}