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

package/src/components/Fieldset/Fieldset.stories.mdx

@@ -0,0 +1,96 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import Fieldset from "./Fieldset";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("Fieldset")}
+  component={Fieldset}
+  decorators={[withDesign]}
+  parameters={{
+    jest: ["Fieldset.test.tsx"],
+  }}
+  argTypes={{
+    children: { table: { disable: true } },
+    className: { control: false },
+    id: { control: false },
+    isLegendHidden: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    showRequiredLabel: {
+      table: { defaultValue: { summary: false } },
+    },
+  }}
+/>
+
+# Fieldset
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.25.3`   |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+
+## Overview
+
+<Description of={Fieldset} />
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="Fieldset"
+    args={{
+      className: undefined,
+      id: "fieldset-id",
+      isLegendHidden: false,
+      isRequired: false,
+      legendText: "This is the legend text",
+      showRequiredLabel: true,
+    }}
+  >
+    {(args) => (
+      <Fieldset {...args}>
+        <p>Text children in the Fieldset component.</p>
+      </Fieldset>
+    )}
+  </Story>
+</Canvas>
+
+<ArgsTable story="Fieldset" />
+
+## Accessibility
+
+This is a simple component but is very important to use when building web forms.
+Syntactically, the `Fieldset` component is used to group form elements. Semantically,
+the form elements that are group should have a similar theme or context. For
+example, when building out a form for a user to create an account, one `Fieldset`
+should be used to group the user's first and last names and another `Fieldset`
+to group the user's address information.
+
+The Reservoir DS implements the `Fieldset` component in the following form
+components:
+
+- `CheckboxGroup`, `DatePicker`, `RadioGroup`.
+
+Resources:
+
+- [W3C Grouping form controls with FIELDSET and LEGEND](https://www.w3.org/TR/2008/WD-WCAG20-TECHS-20080430/H82.html)
+- [GOV.UK Using the fieldset and legend elements](https://accessibility.blog.gov.uk/2016/07/22/using-the-fieldset-and-legend-elements/)
+- [MDN fieldset: The Field Set element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset)

package/src/components/Fieldset/Fieldset.test.tsx

@@ -0,0 +1,155 @@
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
+import Fieldset from "./Fieldset";
+
+describe("Fieldset Accessibility", () => {
+  it("passes axe accessibility", async () => {
+    const { container } = render(
+      <Fieldset id="fieldset" legendText="Legend Text">
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+
+  it("passes axe accessibility with the legend hidden", async () => {
+    const { container } = render(
+      <Fieldset id="fieldset" legendText="Legend Text" isLegendHidden>
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});
+
+describe("Fieldset", () => {
+  it("renders text in a legend and fieldset along with its children", () => {
+    render(
+      <Fieldset id="fieldset" legendText="Legend Text">
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+
+    expect(screen.getByRole("group")).toBeInTheDocument();
+    // `legend` has no HTML role
+    expect(screen.getByText(/Legend Text/i)).toBeInTheDocument();
+    expect(screen.getByText("Some other fields")).toBeInTheDocument();
+  });
+
+  it("renders '(Required)' text in the legend when `isRequired` is true", () => {
+    render(
+      <Fieldset id="fieldset" legendText="Legend Text" isRequired>
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+
+    expect(screen.getByText(/Required/i)).toBeInTheDocument();
+  });
+
+  it("can hide the '(Required)' text in the legend but still show the main text", () => {
+    const { rerender } = render(
+      <Fieldset id="fieldset" legendText="Legend Text" isRequired>
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+
+    expect(screen.getByText(/Required/i)).toBeInTheDocument();
+
+    rerender(
+      <Fieldset
+        id="fieldset"
+        isRequired
+        legendText="Legend Text"
+        showRequiredLabel={false}
+      >
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+
+    expect(screen.getByText(/Legend Text/i)).toBeInTheDocument();
+    expect(screen.queryByText(/Required/i)).not.toBeInTheDocument();
+  });
+
+  it("logs a warning when there is no `id` passed", () => {
+    const warn = jest.spyOn(console, "warn");
+    render(
+      // @ts-ignore: Typescript complains when a required prop is not passed, but
+      // here we don't want to pass the required prop to make sure the warning appears.
+      <Fieldset legendText="Legend Text">
+        <p>Some other fields</p>
+      </Fieldset>
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Fieldset: This component's required `id` prop was not passed."
+    );
+  });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(
+        <Fieldset id="fieldset" legendText="Legend Text">
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+    const required = renderer
+      .create(
+        <Fieldset id="fieldset" legendText="Legend Text" isRequired>
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+    const hiddenHelperText = renderer
+      .create(
+        <Fieldset
+          id="fieldset"
+          legendText="Legend Text"
+          isRequired
+          showRequiredLabel={false}
+        >
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+    const hiddenLegend = renderer
+      .create(
+        <Fieldset id="fieldset" legendText="Legend Text" isLegendHidden>
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Fieldset
+          id="withChakraProps"
+          legendText="Legend Text"
+          p="20px"
+          color="ui.error.primary"
+        >
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <Fieldset
+          id="withOtherProps"
+          legendText="Legend Text"
+          data-testid="props"
+        >
+          <p>Some other fields</p>
+        </Fieldset>
+      )
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(required).toMatchSnapshot();
+    expect(hiddenHelperText).toMatchSnapshot();
+    expect(hiddenLegend).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
+  });
+});

package/src/components/Fieldset/Fieldset.tsx

@@ -0,0 +1,55 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
+import React from "react";
+
+interface FieldsetProps {
+  /** Additional class name to add. */
+  className?: string;
+  /** ID that other components can cross reference for accessibility purposes */
+  id: string;
+  /** Flag to show or hide the text in the `legend` element. False by default. */
+  isLegendHidden?: boolean;
+  /** Flag to render "Required" in the `legend`. True by default. */
+  isRequired?: boolean;
+  /** Text to display in the `legend` element. */
+  legendText?: string;
+  /** Whether or not to display the "(Required)" text in the `legend` text.
+   * True by default. */
+  showRequiredLabel?: boolean;
+}
+
+/**
+ * A wrapper component that renders a `fieldset` element along with a `legend`
+ * element as its first child. Commonly used to wrap form components.
+ */
+export const Fieldset = chakra(
+  ({
+    children,
+    className,
+    id,
+    isLegendHidden = false,
+    isRequired = false,
+    legendText,
+    showRequiredLabel = true,
+    ...rest
+  }: React.PropsWithChildren<FieldsetProps>) => {
+    const styles = useMultiStyleConfig("Fieldset", { isLegendHidden });
+
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Fieldset: This component's required `id` prop was not passed."
+      );
+    }
+
+    return (
+      <Box as="fieldset" id={id} __css={styles} className={className} {...rest}>
+        <legend>
+          {legendText}
+          {showRequiredLabel && isRequired && <span> (Required)</span>}
+        </legend>
+        {children}
+      </Box>
+    );
+  }
+);
+
+export default Fieldset;

package/src/components/Fieldset/__snapshots__/Fieldset.test.tsx.snap

@@ -0,0 +1,89 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Fieldset renders the UI snapshot correctly 1`] = `
+<fieldset
+  className="css-1xdhyk6"
+  id="fieldset"
+>
+  <legend>
+    Legend Text
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;
+
+exports[`Fieldset renders the UI snapshot correctly 2`] = `
+<fieldset
+  className="css-1xdhyk6"
+  id="fieldset"
+>
+  <legend>
+    Legend Text
+    <span>
+       (Required)
+    </span>
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;
+
+exports[`Fieldset renders the UI snapshot correctly 3`] = `
+<fieldset
+  className="css-1xdhyk6"
+  id="fieldset"
+>
+  <legend>
+    Legend Text
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;
+
+exports[`Fieldset renders the UI snapshot correctly 4`] = `
+<fieldset
+  className="css-1xdhyk6"
+  id="fieldset"
+>
+  <legend>
+    Legend Text
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;
+
+exports[`Fieldset renders the UI snapshot correctly 5`] = `
+<fieldset
+  className="css-kle7zy"
+  id="withChakraProps"
+>
+  <legend>
+    Legend Text
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;
+
+exports[`Fieldset renders the UI snapshot correctly 6`] = `
+<fieldset
+  className="css-1xdhyk6"
+  data-testid="props"
+  id="withOtherProps"
+>
+  <legend>
+    Legend Text
+  </legend>
+  <p>
+    Some other fields
+  </p>
+</fieldset>
+`;