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

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

@@ -2,19 +2,17 @@
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 1`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextInput"
     id="myTextInput-label"
   >
     Custom Input Label
-    <div
-      className="css-0"
-    >
-      Required
-    </div>
+    <span>
+       (Required)
+    </span>
   </label>
   <input
     aria-required={true}
@@ -33,19 +31,14 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 1`] = `
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 2`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextInput"
     id="myTextInput-label"
   >
     Custom Input Label
-    <div
-      className="css-0"
-    >
-      Optional
-    </div>
   </label>
   <input
     className="chakra-input css-0"
@@ -63,7 +56,7 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 2`] = `
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 3`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <input
     aria-label="Custom Input Label"
@@ -83,19 +76,17 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 3`] = `
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 4`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextInput"
     id="myTextInput-label"
   >
     Custom Input Label
-    <div
-      className="css-0"
-    >
-      Required
-    </div>
+    <span>
+       (Required)
+    </span>
   </label>
   <input
     aria-describedby="myTextInput-helperText"
@@ -111,40 +102,33 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 4`] = `
     type="text"
   />
   <div
-    aria-disabled={false}
-    className="css-0"
-  >
-    <div
-      aria-atomic={true}
-      aria-live="off"
-      className=" css-0"
-      dangerouslySetInnerHTML={
-        Object {
-          "__html": "Custom helper text",
-        }
+    aria-atomic={true}
+    aria-live="off"
+    className="css-1xdhyk6"
+    dangerouslySetInnerHTML={
+      Object {
+        "__html": "Custom helper text",
       }
-      data-isinvalid={false}
-      id="myTextInput-helperText"
-    />
-  </div>
+    }
+    data-isinvalid={false}
+    id="myTextInput-helperText"
+  />
 </div>
 `;
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 5`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextInput"
     id="myTextInput-label"
   >
     Custom Input Label
-    <div
-      className="css-0"
-    >
-      Required
-    </div>
+    <span>
+       (Required)
+    </span>
   </label>
   <input
     aria-invalid={true}
@@ -160,40 +144,33 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 5`] = `
     type="text"
   />
   <div
-    aria-disabled={false}
-    className="css-0"
-  >
-    <div
-      aria-atomic={true}
-      aria-live="polite"
-      className=" css-0"
-      dangerouslySetInnerHTML={
-        Object {
-          "__html": "There is an error related to this field.",
-        }
+    aria-atomic={true}
+    aria-live="polite"
+    className="css-1xdhyk6"
+    dangerouslySetInnerHTML={
+      Object {
+        "__html": "There is an error related to this field.",
       }
-      data-isinvalid={true}
-      id="myTextInput-helperText"
-    />
-  </div>
+    }
+    data-isinvalid={true}
+    id="myTextInput-helperText"
+  />
 </div>
 `;
 
 exports[`UI Snapshots renders the text input UI snapshot correctly 6`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextInput"
     id="myTextInput-label"
   >
     Custom Input Label
-    <div
-      className="css-0"
-    >
-      Required
-    </div>
+    <span>
+       (Required)
+    </span>
   </label>
   <input
     aria-required={true}
@@ -210,21 +187,67 @@ exports[`UI Snapshots renders the text input UI snapshot correctly 6`] = `
 </div>
 `;
 
+exports[`UI Snapshots renders the text input UI snapshot correctly 7`] = `
+<div
+  className="css-kle7zy"
+>
+  <label
+    className="css-1xdhyk6"
+    htmlFor="chakra"
+    id="chakra-label"
+  >
+    Custom Input Label
+  </label>
+  <input
+    className="chakra-input css-0"
+    disabled={false}
+    id="chakra"
+    onBlur={[Function]}
+    onFocus={[Function]}
+    placeholder="Input Placeholder"
+    required={false}
+    step={null}
+    type="text"
+  />
+</div>
+`;
+
+exports[`UI Snapshots renders the text input UI snapshot correctly 8`] = `
+<div
+  className="css-1xdhyk6"
+  data-testid="props"
+>
+  <label
+    className="css-1xdhyk6"
+    htmlFor="props"
+    id="props-label"
+  >
+    Custom Input Label
+  </label>
+  <input
+    className="chakra-input css-0"
+    disabled={false}
+    id="props"
+    onBlur={[Function]}
+    onFocus={[Function]}
+    placeholder="Input Placeholder"
+    required={false}
+    step={null}
+    type="text"
+  />
+</div>
+`;
+
 exports[`UI Snapshots renders the textarea UI snapshot correctly 1`] = `
 <div
-  className="css-0"
+  className="css-1xdhyk6"
 >
   <label
-    className="css-0"
+    className="css-1xdhyk6"
     htmlFor="myTextarea"
     id="myTextarea-label"
   >
     Custom textarea Label
-    <div
-      className="css-0"
-    >
-      Optional
-    </div>
   </label>
   <textarea
     className="chakra-textarea css-0"

package/src/components/Toggle/Toggle.stories.mdx

@@ -55,17 +55,35 @@ export const sizeEnumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.8`   |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Sizes](#sizes)
+- [Controlled Toggle](#controlled-toggle)
+- [Browser States](#browser-states)
+- [Layouts](#layouts)
+
+## Overview
 
 <Description of={Toggle} />
 
-The Toggle component is used as an alternative for the Checkbox component and returns a boolean response. Like the Checkbox component, the Toggle component can display a label to the right of the toggle and helper/error text below the toggle.
+The `Toggle` component is used as an alternative for the Checkbox component and
+returns a boolean response. Like the Checkbox component, the `Toggle` component
+can display a label to the right of the toggle and helper/error text below the toggle.
 
 ### Best Practices
 
-Toggle components are commonly used for “on/off” switches to perform binary actions that occur immediately after a user “flips the switch.”
+`Toggle` components are commonly used for “on/off” switches to perform binary
+actions that occur immediately after a user “flips the switch.”
+
+The Toggle component label should clarify the action being performed. Labels
+should be short and to the point, often three words or less.
 
-The Toggle component label should clarify the action being performed. Labels should be short and to the point, often three words or less.
+## Component Props
 
 <Canvas>
   <Story
@@ -92,6 +110,24 @@ The Toggle component label should clarify the action being performed. Labels sho
 
 <ArgsTable story="Toggle" />
 
+## Accessibility
+
+The `Toggle` component is implemented using Chakra's `Switch` component. While
+some accessibility resources state that using a `<button>` element is better for
+a toggle or switch component, Chakra UI internally uses a `checkbox` element.
+Because Chakra's `Switch` component handles the internal state so well and its
+styles, we chose this over implementing this component with a `<button>` element.
+
+For comparison and reference, resources that build toggle components with the
+`<button>` element are linked below.
+
+Resources:
+
+- [Chakra UI Switch](https://chakra-ui.com/docs/components/form/switch)
+- [W3C Switch Example Using HTML Button](https://w3c.github.io/aria-practices/examples/switch/switch-button.html)
+- [Inclusive Components Toggle Buttons](https://inclusive-components.design/toggle-button/)
+- [Accessible HTML Toggle Button (Switch)](https://www.erikkroes.nl/blog/accessible-html-toggle-button-switch/)
+
 ## Sizes
 
 <Canvas>
@@ -99,13 +135,18 @@ The Toggle component label should clarify the action being performed. Labels sho
     <SimpleGrid columns="2">
       <VStack align="left" spacing="s">
         <Heading level={3}>Default</Heading>
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle labelText="Off" />
+        <Toggle defaultChecked={true} id="default-checked" labelText="On" />
+        <Toggle id="default" labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Small</Heading>
-        <Toggle size={ToggleSizes.Small} defaultChecked={true} labelText="On" />
-        <Toggle size={ToggleSizes.Small} labelText="Off" />
+        <Toggle
+          defaultChecked={true}
+          id="small-checked"
+          size={ToggleSizes.Small}
+          labelText="On"
+        />
+        <Toggle id="default-small" size={ToggleSizes.Small} labelText="Off" />
       </VStack>
     </SimpleGrid>
   </DSProvider>
@@ -125,17 +166,23 @@ const onChange = (e) => {
   console.log(e.target.value);
 };
 
-<Toggle isChecked={true} onChange={onChange} labelText="Controlled Toggle" />;
+<Toggle
+  id="toggle"
+  isChecked={true}
+  labelText="Controlled Toggle"
+  onChange={onChange}
+/>;
 ```
 
 <Canvas>
   <DSProvider>
     <Toggle
+      id="toggle"
       isChecked={true}
+      labelText="Controlled Toggle"
       onChange={(e) => {
         console.log(e.target.value);
       }}
-      labelText="Controlled Toggle"
     />
   </DSProvider>
 </Canvas>
@@ -147,18 +194,28 @@ const onChange = (e) => {
     <SimpleGrid columns="3">
       <VStack align="left" spacing="s">
         <Heading level={3}>Default</Heading>
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle labelText="Off" />
+        <Toggle defaultChecked={true} id="checked-default2" labelText="On" />
+        <Toggle id="default2" labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Disabled</Heading>
-        <Toggle defaultChecked={true} isDisabled={true} labelText="On" />
-        <Toggle labelText="Off" isDisabled={true} />
+        <Toggle
+          defaultChecked={true}
+          id="disabled-checked"
+          isDisabled={true}
+          labelText="On"
+        />
+        <Toggle id="disabled2" isDisabled={true} labelText="Off" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>Error</Heading>
-        <Toggle defaultChecked={true} labelText="On" isInvalid={true} />
-        <Toggle labelText="Off" isInvalid={true} />
+        <Toggle
+          defaultChecked={true}
+          id="error-default"
+          isInvalid={true}
+          labelText="On"
+        />
+        <Toggle id="error2" isInvalid={true} labelText="Off" />
       </VStack>
     </SimpleGrid>
   </DSProvider>
@@ -171,18 +228,19 @@ const onChange = (e) => {
     <SimpleGrid columns="2">
       <VStack align="left" spacing="s">
         <Heading level={3}>Grouped</Heading>
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
-        <Toggle defaultChecked={true} labelText="On" />
+        <Toggle defaultChecked={true} id="layout1" labelText="On" />
+        <Toggle defaultChecked={true} id="layout2" labelText="On" />
+        <Toggle defaultChecked={true} id="layout3" labelText="On" />
+        <Toggle defaultChecked={true} id="layout4" labelText="On" />
+        <Toggle defaultChecked={true} id="layout5" labelText="On" />
       </VStack>
       <VStack align="left" spacing="s">
         <Heading level={3}>With Helper Text</Heading>
         <Toggle
           defaultChecked={true}
-          labelText="On"
           helperText="Component Helper Text"
+          id="helper-text"
+          labelText="On"
         />
       </VStack>
     </SimpleGrid>

package/src/components/Toggle/Toggle.test.tsx

@@ -6,7 +6,6 @@ import renderer from "react-test-renderer";
 
 import Toggle from "./Toggle";
 import { ToggleSizes } from "./ToggleTypes";
-import * as generateUUID from "../../helpers/generateUUID";
 
 describe("Toggle Accessibility", () => {
   it("Passes axe accessibility test", async () => {
@@ -19,7 +18,6 @@ describe("Toggle Accessibility", () => {
 
 describe("Toggle", () => {
   let changeHandler;
-  let generateUUIDSpy;
 
   beforeEach(() => {
     changeHandler = jest.fn();
@@ -65,13 +63,6 @@ describe("Toggle", () => {
     expect(screen.getByRole("checkbox")).toHaveAttribute("id", "inputID");
   });
 
-  it("Calls the UUID generation function if no id prop value is passed", () => {
-    generateUUIDSpy = jest.spyOn(generateUUID, "default");
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(0);
-    render(<Toggle labelText="Test Label" />);
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(1);
-  });
-
   it("Sets the 'checked' attribute", () => {
     render(<Toggle id="inputID" labelText="Test Label" isChecked />);
     expect(screen.getByRole("checkbox")).toHaveAttribute("checked");
@@ -120,6 +111,18 @@ describe("Toggle", () => {
     expect(changeHandler).toHaveBeenCalledTimes(1);
   });
 
+  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.
+      <Toggle labelText="test" />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir Toggle: This component's required `id` prop was not passed."
+    );
+  });
+
   it("Renders the UI snapshot correctly", () => {
     const primary = renderer
       .create(<Toggle id="inputID" labelText="Test Label" />)
@@ -143,11 +146,26 @@ describe("Toggle", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Toggle
+          id="chakra"
+          labelText="Test Label"
+          p="20px"
+          color="ui.error.primray"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Toggle id="props" labelText="Test Label" data-testid="props" />)
+      .toJSON();
 
     expect(primary).toMatchSnapshot();
     expect(isChecked).toMatchSnapshot();
     expect(isInvalid).toMatchSnapshot();
     expect(isDisabled).toMatchSnapshot();
     expect(small).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Toggle/Toggle.tsx

@@ -1,5 +1,6 @@
 import {
   Box,
+  chakra,
   Switch,
   useMultiStyleConfig,
   useStyleConfig,
@@ -10,8 +11,6 @@ import HelperErrorText, {
   HelperErrorTextType,
 } from "../HelperErrorText/HelperErrorText";
 import { ToggleSizes } from "./ToggleTypes";
-import generateUUID from "../../helpers/generateUUID";
-
 export interface ToggleProps {
   /** Optionally pass in additional Chakra-based styles. */
   additionalStyles?: { [key: string]: any };
@@ -21,7 +20,7 @@ export interface ToggleProps {
   /** Optional string to populate the HelperErrorText for standard state */
   helperText?: HelperErrorTextType;
   /** ID that other components can cross reference for accessibility purposes */
-  id?: string;
+  id: string;
   /** Optional string to populate the HelperErrorText for the error state
    * when `isInvalid` is true. */
   invalidText?: HelperErrorTextType;
@@ -37,8 +36,7 @@ export interface ToggleProps {
   isInvalid?: boolean;
   /** Adds the 'required' attribute to the input when true. */
   isRequired?: boolean;
-  /** The toggle's label. This will serve as the text content for a `<label>`
-   * element if `showlabel` is true, or an "aria-label" if `showLabel` is false. */
+  /** The toggle's label. This will serve as the text content for the `<label>` element */
   labelText: string;
   /** The name prop indicates the `Toggle`'s form element name. If none is
    * specified, 'default' will be used. */
@@ -56,13 +54,13 @@ export const onChangeDefault = () => {
 /**
  * Component that renders Chakra's `Switch` component along with NYPL defaults.
  */
-const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
-  (props, ref?) => {
+export const Toggle = chakra(
+  React.forwardRef<HTMLInputElement, ToggleProps>((props, ref?) => {
     const {
       additionalStyles = {},
       defaultChecked = false,
       helperText,
-      id = generateUUID(),
+      id,
       invalidText,
       isChecked,
       isDisabled = false,
@@ -72,17 +70,24 @@ const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
       name,
       onChange = onChangeDefault,
       size = ToggleSizes.Default,
+      ...rest
     } = props;
     const footnote: HelperErrorTextType = isInvalid ? invalidText : helperText;
     const ariaAttributes = {};
-    const styles = useMultiStyleConfig("Toggle", {});
+    const styles = useMultiStyleConfig("Toggle", { isDisabled, size });
     const switchStyles = useStyleConfig("Switch", { size });
     ariaAttributes["aria-label"] =
       labelText && footnote ? `${labelText} - ${footnote}` : labelText;
 
+    if (!id) {
+      console.warn(
+        "NYPL Reservoir Toggle: This component's required `id` prop was not passed."
+      );
+    }
+
     return (
       <>
-        <Box __css={{ ...styles, ...additionalStyles }}>
+        <Box __css={{ ...styles, ...additionalStyles }} {...rest}>
           <Switch
             id={id}
             name={name || "default"}
@@ -107,17 +112,16 @@ const Toggle = React.forwardRef<HTMLInputElement, ToggleProps>(
           </Switch>
         </Box>
         {footnote && (
-          <Box __css={styles.helper}>
-            <HelperErrorText
-              id={`${id}-helperText`}
-              isInvalid={isInvalid}
-              text={footnote}
-            />
-          </Box>
+          <HelperErrorText
+            additionalStyles={styles.helperErrorText}
+            id={`${id}-helperText`}
+            isInvalid={isInvalid}
+            text={footnote}
+          />
         )}
       </>
     );
-  }
+  })
 );
 
 export default Toggle;