@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,360 @@
+import { Box } from "@chakra-ui/react";
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import ProgressIndicator from "./ProgressIndicator";
+import SimpleGrid from "../Grid/SimpleGrid";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<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={{
+    darkMode: {
+      table: { defaultValue: { summary: false } },
+    },
+    id: { control: false },
+    indicatorType: {
+      table: { defaultValue: { summary: "linear" } },
+    },
+    isIndeterminate: {
+      table: { defaultValue: { summary: false } },
+    },
+    showLabel: {
+      table: { defaultValue: { summary: true } },
+    },
+    size: {
+      table: { defaultValue: { summary: "default" } },
+    },
+    value: {
+      table: { defaultValue: { summary: 0 } },
+    },
+  }}
+/>
+
+# ProgressIndicator
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.4`   |
+| Latest            | `0.28.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Linear Type](#linear-type)
+- [Circular Type](#circular-type)
+- [Sizing](#sizing)
+- [Labels](#labels)
+- [Indeterminate State](#indeterminate-state)
+- [Dark Mode](#dark-mode)
+- [Get Input Values](#get-input-values)
+
+## Overview
+
+<Description of={ProgressIndicator} />
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="ProgressIndicator with Controls"
+    args={{
+      darkMode: false,
+      id: "progressIndicator-id",
+      indicatorType: "linear",
+      isIndeterminate: false,
+      labelText: "Progress",
+      showLabel: true,
+      size: "default",
+      value: 50,
+    }}
+  >
+    {(args) => <ProgressIndicator {...args} />}
+  </Story>
+</Canvas>
+
+<ArgsTable story="ProgressIndicator with Controls" />
+
+## Accessibility
+
+Chakra UI takes care of the internal accessibility attributes for this component.
+Specifically, the `role` attribute is set to `progressbar` and the `aria-valuenow`
+attribute is set to the value of the `value` prop, or the percentage completion
+value. The min and max values are set to "0" and "100", respectively, and are set
+with the `aria-valuemin` and `aria-valuemax` attributes. This makes this
+component and its value(s) visible to screen readers.
+
+When `showLabel` is set to false, the `labelText` value will be set to the
+main `<div>`'s `aria-label` attribute. This is the same div that contains the
+`aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes.
+
+Resources:
+
+- [DigitalA11y WAI-ARIA: ROLE=PROGRESSBAR](https://www.digitala11y.com/progressbar-role/)
+- [MDN Using the progressbar role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_progressbar_role)
+- [Chakra UI Progress](https://chakra-ui.com/docs/components/feedback/progress)
+- [Chakra UI Circular Progress](https://chakra-ui.com/docs/components/feedback/circular-progress)
+
+## Linear Type
+
+Progress bars are preferred in vertically narrow areas such as tables, cards,
+dialogs, etc.
+
+<Canvas>
+  <Story
+    name="Linear Type"
+    argTypes={{
+      indicatorType: { table: { disable: true } },
+    }}
+  >
+    <ProgressIndicator
+      id="linear"
+      indicatorType="linear"
+      labelText="Linear Progress Type"
+      value={50}
+    />
+  </Story>
+</Canvas>
+
+## Circular Type
+
+The circular progress type is preferred for large content areas and for
+full-screen loading. Set the `indicatorType` prop to `"circular"` for this type.
+
+<Canvas>
+  <Story
+    name="Circular Type"
+    argTypes={{
+      indicatorType: { table: { disable: true } },
+    }}
+  >
+    <ProgressIndicator
+      id="circular"
+      indicatorType="circular"
+      labelText="Linear Progress Type"
+      value={50}
+    />
+  </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="small"`
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap="grid.m">
+      <ProgressIndicator
+        id="default-size"
+        labelText="Default 8px size"
+        value={50}
+      />
+      <ProgressIndicator
+        id="small-size"
+        labelText="Small 4px size"
+        size="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="small"`
+
+<Canvas>
+  <DSProvider>
+    <SimpleGrid columns={1} gap="grid.m">
+      <ProgressIndicator
+        id="default-size"
+        indicatorType="circular"
+        labelText="Default 48px size"
+        value={50}
+      />
+      <ProgressIndicator
+        id="small-size"
+        indicatorType="circular"
+        labelText="Small 24px size"
+        size="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="grid.m">
+      <ProgressIndicator
+        id="label"
+        labelText="This label will be added through aria-label"
+        showLabel={false}
+        value={50}
+      />
+      <ProgressIndicator
+        id="label-hidden"
+        indicatorType="circular"
+        labelText="This label will be added through aria-label"
+        showLabel={false}
+        value={50}
+      />
+    </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="grid.m">
+      <ProgressIndicator
+        id="indeterminate"
+        isIndeterminate
+        labelText="Indeterminate state"
+        value={50}
+      />
+      <ProgressIndicator
+        id="indeterminate-circular"
+        indicatorType="circular"
+        isIndeterminate
+        labelText="Indeterminate state"
+        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="grid.m">
+        <ProgressIndicator
+          darkMode
+          id="darkmode"
+          labelText="Dark Mode"
+          value={50}
+        />
+        <ProgressIndicator
+          darkMode
+          id="darkmode-circular"
+          indicatorType="circular"
+          labelText="Dark Mode"
+          value={50}
+        />
+      </SimpleGrid>
+    </Box>
+  </DSProvider>
+</Canvas>
+
+## Get Input Values
+
+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="grid.m">
+      <ProgressIndicator
+        id="example"
+        labelText="Progress example"
+        value={value}
+      />
+      <ProgressIndicator
+        id="example-circular"
+        indicatorType="circular"
+        labelText="Progress example"
+        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="grid.m">
+      <ProgressIndicator
+        id="example"
+        labelText="Progress example"
+        value={value}
+      />
+      <ProgressIndicator
+        id="example-circular"
+        indicatorType="circular"
+        labelText="Progress example"
+        value={value}
+      />
+    </SimpleGrid>
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <ProgressIndicatorExample />
+  </DSProvider>
+</Canvas>

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

@@ -0,0 +1,298 @@
+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";
+
+describe("ProgressIndicator Accessibility", () => {
+  it("passes axe accessibility for linear and circular types", async () => {
+    const linearUtils = render(
+      <ProgressIndicator
+        id="progressIndicatorLinear"
+        labelText="Linear"
+        value={50}
+      />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        id="progressIndicatorCircular"
+        labelText="Circular"
+        value={50}
+        indicatorType="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
+        id="progressIndicatorLinear"
+        labelText="Linear"
+        value={50}
+        showLabel={false}
+      />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        id="progressIndicatorCircular"
+        labelText="Circular"
+        value={50}
+        indicatorType="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
+        id="progressIndicatorLinear"
+        labelText="Linear"
+        value={50}
+        isIndeterminate
+      />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        id="progressIndicatorCircular"
+        labelText="Circular"
+        value={50}
+        indicatorType="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
+        id="progressIndicatorLinear"
+        labelText="Linear"
+        value={50}
+        darkMode
+      />
+    );
+    const circularUtils = render(
+      <ProgressIndicator
+        id="progressIndicatorCircular"
+        labelText="Circular"
+        value={50}
+        indicatorType="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 id="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
+        id="progressIndicator"
+        labelText="Circular"
+        indicatorType="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
+        id="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 id="progressIndicator" labelText="Linear" value={50} />
+    );
+    expect(screen.getByText("50%")).toBeInTheDocument();
+
+    rerender(
+      <ProgressIndicator id="progressIndicator" labelText="Linear" value={89} />
+    );
+    expect(screen.getByText("89%")).toBeInTheDocument();
+
+    rerender(
+      <ProgressIndicator id="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
+        id="progressIndicator"
+        labelText="Linear"
+        value={-20}
+      />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir ProgressIndicator: An invalid value was passed for the" +
+        " `value` prop, so 0 will be used. A valid value should be a number" +
+        " between 0 and 100."
+    );
+  });
+
+  it("logs a warning if a value more than 100 is passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      <ProgressIndicator
+        id="progressIndicator"
+        labelText="Linear"
+        value={150}
+      />
+    );
+
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir ProgressIndicator: An invalid value was passed for the" +
+        " `value` prop, so 0 will be used. A valid value should be a number" +
+        " between 0 and 100."
+    );
+  });
+
+  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="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="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="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="circular"
+          darkMode
+        />
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <ProgressIndicator
+          id="chakra"
+          labelText="Linear"
+          value={50}
+          p="20px"
+          color="ui.red.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <ProgressIndicator
+          id="props"
+          labelText="Linear"
+          value={50}
+          data-testid="props"
+        />
+      )
+      .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();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});