@nypl/design-system-react-components 0.25.13 → 0.26.0

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

@@ -28,7 +28,7 @@ import DSProvider from "../../theme/provider";
     isRequired: {
       table: { defaultValue: { summary: false } },
     },
-    optReqFlag: {
+    showRequiredLabel: {
       table: { defaultValue: { summary: false } },
     },
   }}
@@ -39,10 +39,20 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.3`   |
-| Latest            | `0.25.12`  |
+| 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"
@@ -52,7 +62,7 @@ import DSProvider from "../../theme/provider";
       isLegendHidden: false,
       isRequired: false,
       legendText: "This is the legend text",
-      optReqFlag: true,
+      showRequiredLabel: true,
     }}
   >
     {(args) => (
@@ -64,3 +74,23 @@ import DSProvider from "../../theme/provider";
 </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

@@ -8,7 +8,7 @@ import Fieldset from "./Fieldset";
 describe("Fieldset Accessibility", () => {
   it("passes axe accessibility", async () => {
     const { container } = render(
-      <Fieldset legendText="Legend Text">
+      <Fieldset id="fieldset" legendText="Legend Text">
         <p>Some other fields</p>
       </Fieldset>
     );
@@ -17,7 +17,7 @@ describe("Fieldset Accessibility", () => {
 
   it("passes axe accessibility with the legend hidden", async () => {
     const { container } = render(
-      <Fieldset legendText="Legend Text" isLegendHidden>
+      <Fieldset id="fieldset" legendText="Legend Text" isLegendHidden>
         <p>Some other fields</p>
       </Fieldset>
     );
@@ -28,7 +28,7 @@ describe("Fieldset Accessibility", () => {
 describe("Fieldset", () => {
   it("renders text in a legend and fieldset along with its children", () => {
     render(
-      <Fieldset legendText="Legend Text">
+      <Fieldset id="fieldset" legendText="Legend Text">
         <p>Some other fields</p>
       </Fieldset>
     );
@@ -39,19 +39,9 @@ describe("Fieldset", () => {
     expect(screen.getByText("Some other fields")).toBeInTheDocument();
   });
 
-  it("renders 'Optional' text by default in the legend", () => {
+  it("renders '(Required)' text in the legend when `isRequired` is true", () => {
     render(
-      <Fieldset legendText="Legend Text">
-        <p>Some other fields</p>
-      </Fieldset>
-    );
-
-    expect(screen.getByText(/Optional/i)).toBeInTheDocument();
-  });
-
-  it("renders 'Required' text in the legend", () => {
-    render(
-      <Fieldset legendText="Legend Text" isRequired>
+      <Fieldset id="fieldset" legendText="Legend Text" isRequired>
         <p>Some other fields</p>
       </Fieldset>
     );
@@ -59,9 +49,9 @@ describe("Fieldset", () => {
     expect(screen.getByText(/Required/i)).toBeInTheDocument();
   });
 
-  it("can hide the 'Required'/'Optional' text in the legend but still show the main text", () => {
+  it("can hide the '(Required)' text in the legend but still show the main text", () => {
     const { rerender } = render(
-      <Fieldset legendText="Legend Text" isRequired>
+      <Fieldset id="fieldset" legendText="Legend Text" isRequired>
         <p>Some other fields</p>
       </Fieldset>
     );
@@ -69,49 +59,87 @@ describe("Fieldset", () => {
     expect(screen.getByText(/Required/i)).toBeInTheDocument();
 
     rerender(
-      <Fieldset legendText="Legend Text" optReqFlag={false}>
+      <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(/Optional/i)).not.toBeInTheDocument();
+    expect(screen.queryByText(/Required/i)).not.toBeInTheDocument();
+  });
 
-    rerender(
-      <Fieldset legendText="Legend Text" isRequired optReqFlag={false}>
+  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(screen.getByText(/Legend Text/i)).toBeInTheDocument();
-    expect(screen.queryByText(/Required/i)).not.toBeInTheDocument();
+    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 legendText="Legend Text">
+        <Fieldset id="fieldset" legendText="Legend Text">
           <p>Some other fields</p>
         </Fieldset>
       )
       .toJSON();
     const required = renderer
       .create(
-        <Fieldset legendText="Legend Text" isRequired>
+        <Fieldset id="fieldset" legendText="Legend Text" isRequired>
           <p>Some other fields</p>
         </Fieldset>
       )
       .toJSON();
     const hiddenHelperText = renderer
       .create(
-        <Fieldset legendText="Legend Text" isRequired optReqFlag={false}>
+        <Fieldset
+          id="fieldset"
+          legendText="Legend Text"
+          isRequired
+          showRequiredLabel={false}
+        >
           <p>Some other fields</p>
         </Fieldset>
       )
       .toJSON();
     const hiddenLegend = renderer
       .create(
-        <Fieldset legendText="Legend Text" isLegendHidden>
+        <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>
       )
@@ -121,5 +149,7 @@ describe("Fieldset", () => {
     expect(required).toMatchSnapshot();
     expect(hiddenHelperText).toMatchSnapshot();
     expect(hiddenLegend).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Fieldset/Fieldset.tsx

@@ -1,50 +1,55 @@
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
 import React from "react";
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
 
 interface FieldsetProps {
   /** Additional class name to add. */
   className?: string;
   /** ID that other components can cross reference for accessibility purposes */
-  id?: string;
+  id: string;
   /** Flag to show or hide the text in the `legend` element. False by default. */
   isLegendHidden?: boolean;
-  /** Flag to render "Required" or "Optional" in the `legend`.
-   * False/"Optional" by default. */
+  /** Flag to render "Required" in the `legend`. True by default. */
   isRequired?: boolean;
   /** Text to display in the `legend` element. */
   legendText?: string;
-  /** Flag to show or hide the "Required"/"Optional" text in the `legend`.
+  /** Whether or not to display the "(Required)" text in the `legend` text.
    * True by default. */
-  optReqFlag?: boolean;
+  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.
  */
-const Fieldset = ({
-  children,
-  className,
-  id,
-  isLegendHidden = false,
-  isRequired = false,
-  legendText,
-  optReqFlag = true,
-}: React.PropsWithChildren<FieldsetProps>) => {
-  const styles = useMultiStyleConfig("Fieldset", { isLegendHidden });
-  return (
-    <Box as="fieldset" id={id} __css={styles} className={className}>
-      <legend>
-        {legendText}
-        {optReqFlag && (
-          <Box __css={styles.helper}>
-            {isRequired ? "Required" : "Optional"}
-          </Box>
-        )}
-      </legend>
-      {children}
-    </Box>
-  );
-};
+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

@@ -2,15 +2,11 @@
 
 exports[`Fieldset renders the UI snapshot correctly 1`] = `
 <fieldset
-  className="css-0"
+  className="css-1xdhyk6"
+  id="fieldset"
 >
   <legend>
     Legend Text
-    <div
-      className="css-0"
-    >
-      Optional
-    </div>
   </legend>
   <p>
     Some other fields
@@ -20,15 +16,14 @@ exports[`Fieldset renders the UI snapshot correctly 1`] = `
 
 exports[`Fieldset renders the UI snapshot correctly 2`] = `
 <fieldset
-  className="css-0"
+  className="css-1xdhyk6"
+  id="fieldset"
 >
   <legend>
     Legend Text
-    <div
-      className="css-0"
-    >
-      Required
-    </div>
+    <span>
+       (Required)
+    </span>
   </legend>
   <p>
     Some other fields
@@ -38,7 +33,8 @@ exports[`Fieldset renders the UI snapshot correctly 2`] = `
 
 exports[`Fieldset renders the UI snapshot correctly 3`] = `
 <fieldset
-  className="css-0"
+  className="css-1xdhyk6"
+  id="fieldset"
 >
   <legend>
     Legend Text
@@ -51,15 +47,40 @@ exports[`Fieldset renders the UI snapshot correctly 3`] = `
 
 exports[`Fieldset renders the UI snapshot correctly 4`] = `
 <fieldset
-  className="css-0"
+  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
-    <div
-      className="css-0"
-    >
-      Optional
-    </div>
   </legend>
   <p>
     Some other fields