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

package/src/components/TextInput/TextInput.stories.mdx

@@ -41,7 +41,7 @@ export const enumValues = getStorybookEnumValues(
     ref: { table: { disable: true } },
     showHelperInvalidText: { table: { defaultValue: { summary: true } } },
     showLabel: { table: { defaultValue: { summary: true } } },
-    showOptReqLabel: { table: { defaultValue: { summary: true } } },
+    showRequiredLabel: { table: { defaultValue: { summary: true } } },
     step: { table: { defaultValue: { summary: 1 } } },
     textInputType: {
       control: false,
@@ -61,7 +61,18 @@ export const enumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.22.0`   |
-| Latest            | `0.25.13`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Labelling Variations](#labelling-variations)
+- [HTML in Helper Text](#html-in-helper-text)
+- [Textarea](#textarea)
+
+## Overview
 
 <Description of={TextInput} />
 
@@ -71,6 +82,8 @@ prop, regardless of the label visibility. Additionally, while the `id` prop is
 optional, a unique `id` attribute is necessary for accessibility. If the prop
 is left blank, a value will be generated for you.
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="TextInput with Controls"
@@ -91,7 +104,7 @@ is left blank, a value will be generated for you.
       placeholder: "e.g. blue, green, etc.",
       showHelperInvalidText: true,
       showLabel: true,
-      showOptReqLabel: true,
+      showRequiredLabel: true,
       step: 1,
       type: "TextInputTypes.text",
       value: undefined,
@@ -104,43 +117,71 @@ is left blank, a value will be generated for you.
 
 <ArgsTable story="TextInput with Controls" />
 
+## Accessibility
+
+The `TextInput` component renders an HTML `<input>` element which is accessible
+via keyboard and screen reader. The `aria-required` and `required` attributes are
+set with the `isRequired` prop. The `aria-disabled` and `disabled` attributes are
+set with the `isDisabled` prop. The `aria-invalid` is set with the `isInvalid`
+prop.
+
+Internally, a `Label` is associated with the `<input>` element. When `showLabel`
+is set to false, the `<input>` element's `aria-label` attribute is set to the
+required `labelText` value.
+
+When the `type` prop is set to `TextInputTypes.textarea`, the `<textarea>` element
+is rendered instead of the `<input>` element. This element follows all the same
+accessibility rules described above.
+
+Resources:
+
+- [MDN input: The Input (Form Input) element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
+- [MDN textarea: The Textarea element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
+- [Chakra UI Input](https://chakra-ui.com/docs/components/form/input)
+- [Chakra UI Textarea](https://chakra-ui.com/docs/components/form/textarea)
+
 ## Labelling Variations
 
 A TextInput can be rendered with or without visible labels. When `showLabel` is
 set to `false`, an `aria-label` attribute is added to the input/textarea element
 to maintain accessibility. If the component needs to be required, the
-`showOptReqLabel` prop can be used to show or hide the "Required"/"Optional"
-text within the `label` element.
+`showRequiredLabel` prop can be used to show or hide the "(Required)" text
+within the `label` element.
 
 <Canvas withToolbar>
   <Story name="Labelling Variations">
     <VStack align="stretch" spacing={12}>
       <TextInput
+        helperText="Choose wisely!"
+        id="textInput-1"
         labelText="What is your favorite color?"
         placeholder="i.e. blue, green, etc."
-        helperText="Choose wisely!"
       />
       <TextInput
+        id="textInput-2"
         labelText="What is your favorite color?"
         placeholder="i.e. blue, green, etc."
         showLabel={false}
       />
       <TextInput
+        id="textInput-3"
+        isRequired
         labelText="What is your favorite color?"
         placeholder="i.e. blue, green, etc."
-        isRequired
       />
       <TextInput
+        id="textInput-4"
+        isRequired
         labelText="What is your favorite color?"
         placeholder="i.e. blue, green, etc."
-        showOptReqLabel={false}
-        isRequired
+        showRequiredLabel={false}
       />
       <TextInput
+        helperText="Choose wisely!"
+        id="textInput-5"
         labelText="What is your favorite color?"
-        showLabel={false}
         placeholder="i.e. blue, green, etc."
-        helperText="Choose wisely!"
+        showLabel={false}
       />
     </VStack>
   </Story>
@@ -151,11 +192,12 @@ text within the `label` element.
 <Canvas>
   <DSProvider>
     <TextInput
-      labelText="What is your favorite color?"
-      placeholder="i.e. blue, green, etc."
       helperText="Choose wisely!"
+      id="errored"
       invalidText="This is error text :("
       isInvalid
+      labelText="What is your favorite color?"
+      placeholder="i.e. blue, green, etc."
     />
   </DSProvider>
 </Canvas>
@@ -165,10 +207,11 @@ text within the `label` element.
 <Canvas>
   <DSProvider>
     <TextInput
-      labelText="What is your favorite color?"
-      placeholder="i.e. blue, green, etc."
       helperText="Choose wisely!"
+      id="disabled"
       isDisabled
+      labelText="What is your favorite color?"
+      placeholder="i.e. blue, green, etc."
     />
   </DSProvider>
 </Canvas>
@@ -186,19 +229,21 @@ helperText={<>Choose <b>wisely!</b></>}
 <Canvas>
   <DSProvider>
     <TextInput
+      helperText="Choose <b>wisely!</b>"
+      id="string"
       labelText="What is your favorite color?"
       placeholder="i.e. blue, green, etc."
-      helperText="Choose <b>wisely!</b>"
     />
     <br />
     <TextInput
-      labelText="What is your favorite color?"
-      placeholder="i.e. blue, green, etc."
       helperText={
         <>
           Choose <b>wisely!</b>
         </>
       }
+      id="jsx"
+      labelText="What is your favorite color?"
+      placeholder="i.e. blue, green, etc."
     />
   </DSProvider>
 </Canvas>
@@ -214,6 +259,7 @@ All the variations described above are available for the `textarea` option.
     name="Textarea"
     args={{
       helperText: "Let it all out.",
+      id: "textarea",
       invalidText: "This is error text :(",
       isDisabled: false,
       isInvalid: false,
@@ -221,7 +267,7 @@ All the variations described above are available for the `textarea` option.
       labelText: "In less than 500 words, describe your favorite color?",
       placeholder: "Essay question...",
       showLabel: true,
-      showOptReqLabel: true,
+      showRequiredLabel: true,
       type: TextInputTypes.textarea,
     }}
     argTypes={{

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

@@ -6,12 +6,12 @@ import userEvent from "@testing-library/user-event";
 
 import TextInput from "./TextInput";
 import { TextInputTypes } from "./TextInputTypes";
-import * as generateUUID from "../../helpers/generateUUID";
 
 describe("TextInput Accessibility", () => {
   it("passes axe accessibility test for the input element", async () => {
     const { container } = render(
       <TextInput
+        id="textInput"
         isRequired
         labelText="Custom input label"
         onChange={jest.fn()}
@@ -25,6 +25,7 @@ describe("TextInput Accessibility", () => {
   it("passes axe accessibility test for the textarea element", async () => {
     const { container } = render(
       <TextInput
+        id="textInput"
         isRequired
         labelText="Custom textarea label"
         onChange={jest.fn()}
@@ -70,24 +71,7 @@ describe("TextInput", () => {
     expect(screen.getByText(/Required/i)).toBeInTheDocument();
   });
 
-  it("renders 'Optional' along with the label text", () => {
-    utils.rerender(
-      <TextInput
-        attributes={{ onFocus: focusHandler }}
-        id="myTextInput"
-        isRequired={false}
-        labelText="Custom Input Label"
-        onChange={changeHandler}
-        placeholder="Input Placeholder"
-        type={TextInputTypes.text}
-      />
-    );
-
-    expect(screen.getByText("Custom Input Label")).toBeInTheDocument();
-    expect(screen.getByText(/Optional/i)).toBeInTheDocument();
-  });
-
-  it("does not render 'Required' along with the label text", () => {
+  it("does not render '(Required)' along with the label text", () => {
     utils.rerender(
       <TextInput
         attributes={{ onFocus: focusHandler }}
@@ -96,7 +80,7 @@ describe("TextInput", () => {
         labelText="Custom Input Label"
         onChange={changeHandler}
         placeholder="Input Placeholder"
-        showOptReqLabel={false}
+        showRequiredLabel={false}
         type={TextInputTypes.text}
       />
     );
@@ -136,16 +120,26 @@ describe("TextInput", () => {
     // Called 5 times because "Hello" has length of 5.
     expect(changeHandler).toHaveBeenCalledTimes(5);
   });
+
+  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.
+      <TextInput labelText="Custom Input Label" />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir TextInput: This component's required `id` prop was not passed."
+    );
+  });
 });
 
 describe("Renders TextInput with auto-generated ID, hidden label and visible helper text", () => {
-  let generateUUIDSpy;
-
   beforeEach(() => {
-    generateUUIDSpy = jest.spyOn(generateUUID, "default");
     render(
       <TextInput
         helperText="Custom Helper Text"
+        id="textInput"
         isRequired
         labelText="Custom Input Label"
         placeholder="Input Placeholder"
@@ -159,11 +153,6 @@ describe("Renders TextInput with auto-generated ID, hidden label and visible hel
     expect(screen.getByLabelText(/Custom Input Label/i)).toBeInTheDocument();
   });
 
-  it("calls a UUID generation method if no ID is passed as a prop", () => {
-    // Called twice for the `TextInput` and the SVG icon components.
-    expect(generateUUIDSpy).toHaveBeenCalledTimes(2);
-  });
-
   it("does not renders Label component", () => {
     expect(screen.queryByText(/Custom Input Label/i)).not.toBeInTheDocument();
   });
@@ -441,6 +430,29 @@ describe("UI Snapshots", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <TextInput
+          id="chakra"
+          labelText="Custom Input Label"
+          placeholder="Input Placeholder"
+          type={TextInputTypes.text}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <TextInput
+          id="props"
+          labelText="Custom Input Label"
+          placeholder="Input Placeholder"
+          type={TextInputTypes.text}
+          data-testid="props"
+        />
+      )
+      .toJSON();
 
     expect(required).toMatchSnapshot();
     expect(optional).toMatchSnapshot();
@@ -448,6 +460,8 @@ describe("UI Snapshots", () => {
     expect(withHelperText).toMatchSnapshot();
     expect(errorState).toMatchSnapshot();
     expect(disabledState).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 
   it("renders the textarea UI snapshot correctly", () => {

package/src/components/TextInput/TextInput.tsx

@@ -1,10 +1,11 @@
-import * as React from "react";
 import {
   Box,
+  chakra,
   Input as ChakraInput,
   Textarea as ChakraTextarea,
   useMultiStyleConfig,
 } from "@chakra-ui/react";
+import * as React from "react";
 
 import {
   TextInputTypes,
@@ -15,7 +16,6 @@ import Label from "../Label/Label";
 import HelperErrorText, {
   HelperErrorTextType,
 } from "../HelperErrorText/HelperErrorText";
-import generateUUID from "../../helpers/generateUUID";
 
 export interface InputProps {
   /** Optionally pass in additional Chakra-based styles. */
@@ -29,7 +29,7 @@ export interface InputProps {
   /** Populates the HelperErrorText for the standard state */
   helperText?: HelperErrorTextType;
   /** ID that other components can cross reference for accessibility purposes */
-  id?: string;
+  id: string;
   /** Populates the HelperErrorText for the error state */
   invalidText?: HelperErrorTextType;
   /** Adds the `disabled` and `aria-disabled` prop to the input when true */
@@ -56,9 +56,9 @@ export interface InputProps {
   /** Offers the ability to show the label onscreen or hide it. Refer to the
    * `labelText` property for more information. */
   showLabel?: boolean;
-  /** Offers the ability to show the "Required"/"Optional" label onscreen or
-   * hide it. True by default. */
-  showOptReqLabel?: boolean;
+  /** Whether or not to display the "(Required)" text in the label text.
+   * True by default. */
+  showRequiredLabel?: boolean;
   /** The amount to increase or decrease when using the number type. */
   step?: number;
   /** FOR INTERNAL DS USE ONLY: the input variant to display. */
@@ -80,122 +80,130 @@ export type TextInputRefType = HTMLInputElement & HTMLTextAreaElement;
  * element. All types will render an accessible `Label` component and an
  * optional `HelperErrorText` component.
  */
-const TextInput = React.forwardRef<TextInputRefType, InputProps>(
-  (props, ref: React.Ref<TextInputRefType>) => {
-    const {
-      additionalStyles = {},
-      attributes = {},
-      className,
-      defaultValue,
-      helperText,
-      id = generateUUID(),
-      invalidText,
-      isDisabled = false,
-      isInvalid = false,
-      isRequired = false,
-      labelText,
-      name,
-      onChange,
-      placeholder,
-      showHelperInvalidText = true,
-      showLabel = true,
-      showOptReqLabel = true,
-      step = 1,
-      textInputType = TextInputVariants.Default,
-      type = TextInputTypes.text,
-      value,
-    } = props;
-    const styles = useMultiStyleConfig("TextInput", { variant: textInputType });
-    const finalStyles = { ...styles, ...additionalStyles };
-    const isTextArea = type === TextInputTypes.textarea;
-    const isHidden = type === TextInputTypes.hidden;
-    const optReqFlag = isRequired ? "Required" : "Optional";
-    const finalInvalidText = invalidText
-      ? invalidText
-      : "There is an error related to this field.";
-    let footnote: HelperErrorTextType = isInvalid
-      ? finalInvalidText
-      : helperText;
-    let fieldOutput;
-    let options;
+export const TextInput = chakra(
+  React.forwardRef<TextInputRefType, InputProps>(
+    (props, ref: React.Ref<TextInputRefType>) => {
+      const {
+        additionalStyles = {},
+        attributes = {},
+        className,
+        defaultValue,
+        helperText,
+        id,
+        invalidText,
+        isDisabled = false,
+        isInvalid = false,
+        isRequired = false,
+        labelText,
+        name,
+        onChange,
+        placeholder,
+        showHelperInvalidText = true,
+        showLabel = true,
+        showRequiredLabel = true,
+        step = 1,
+        textInputType = TextInputVariants.Default,
+        type = TextInputTypes.text,
+        value,
+        ...rest
+      } = props;
+      const styles = useMultiStyleConfig("TextInput", {
+        variant: textInputType,
+      });
+      const finalStyles = { ...styles, ...additionalStyles };
+      const isTextArea = type === TextInputTypes.textarea;
+      const isHidden = type === TextInputTypes.hidden;
+      const finalInvalidText = invalidText
+        ? invalidText
+        : "There is an error related to this field.";
+      let footnote: HelperErrorTextType = isInvalid
+        ? finalInvalidText
+        : helperText;
+      let fieldOutput;
+      let options;
 
-    if (!showLabel) {
-      attributes["aria-label"] =
-        labelText && footnote ? `${labelText} - ${footnote}` : labelText;
-    } else if (helperText) {
-      attributes["aria-describedby"] = `${id}-helperText`;
-    }
+      if (!id) {
+        console.warn(
+          "NYPL Reservoir TextInput: This component's required `id` prop was not passed."
+        );
+      }
 
-    if (
-      type === TextInputTypes.tel ||
-      type === TextInputTypes.url ||
-      type === TextInputTypes.email
-    ) {
-      const example = TextInputFormats[type];
-      footnote = (
-        <>
-          Ex: {example}
-          <br />
-          {footnote}
-        </>
-      );
-    }
+      if (!showLabel) {
+        attributes["aria-label"] =
+          labelText && footnote ? `${labelText} - ${footnote}` : labelText;
+      } else if (helperText) {
+        attributes["aria-describedby"] = `${id}-helperText`;
+      }
 
-    // When the type is "hidden", the input element needs fewer attributes.
-    options = isHidden
-      ? { id, "aria-hidden": isHidden, name, onChange, ref }
-      : {
-          "aria-required": isRequired,
-          defaultValue,
-          id,
-          isDisabled,
-          isRequired,
-          isInvalid,
-          placeholder,
-          name,
-          onChange,
-          ref,
-          // The `step` attribute is useful for the number type.
-          step: type === TextInputTypes.number ? step : null,
-          ...attributes,
-        };
-    // For `input` and `textarea`, all attributes are the same but `input`
-    // also needs `type` and `value` to render correctly.
-    if (!isTextArea) {
-      options = { type, value, ...options } as any;
-      fieldOutput = <ChakraInput {...options} __css={finalStyles.input} />;
-    } else {
-      fieldOutput = (
-        <ChakraTextarea {...options} __css={finalStyles.textarea}>
-          {value}
-        </ChakraTextarea>
-      );
-    }
+      if (
+        type === TextInputTypes.tel ||
+        type === TextInputTypes.url ||
+        type === TextInputTypes.email
+      ) {
+        const example = TextInputFormats[type];
+        footnote = (
+          <>
+            Ex: {example}
+            <br />
+            {footnote}
+          </>
+        );
+      }
+
+      // When the type is "hidden", the input element needs fewer attributes.
+      options = isHidden
+        ? { id, "aria-hidden": isHidden, name, onChange, ref }
+        : {
+            "aria-required": isRequired,
+            defaultValue,
+            id,
+            isDisabled,
+            isRequired,
+            isInvalid,
+            placeholder,
+            name,
+            onChange,
+            ref,
+            // The `step` attribute is useful for the number type.
+            step: type === TextInputTypes.number ? step : null,
+            ...attributes,
+          };
+      // For `input` and `textarea`, all attributes are the same but `input`
+      // also needs `type` and `value` to render correctly.
+      if (!isTextArea) {
+        options = { type, value, ...options } as any;
+        fieldOutput = <ChakraInput {...options} __css={finalStyles.input} />;
+      } else {
+        fieldOutput = (
+          <ChakraTextarea {...options} __css={finalStyles.textarea}>
+            {value}
+          </ChakraTextarea>
+        );
+      }
 
-    return (
-      <Box __css={finalStyles} className={className}>
-        {labelText && showLabel && !isHidden && (
-          <Label
-            htmlFor={id}
-            optReqFlag={showOptReqLabel && optReqFlag}
-            id={`${id}-label`}
-          >
-            {labelText}
-          </Label>
-        )}
-        {fieldOutput}
-        {footnote && showHelperInvalidText && !isHidden && (
-          <Box __css={finalStyles.helper} aria-disabled={isDisabled}>
+      return (
+        <Box __css={finalStyles} className={className} {...rest}>
+          {labelText && showLabel && !isHidden && (
+            <Label
+              htmlFor={id}
+              id={`${id}-label`}
+              isRequired={showRequiredLabel && isRequired}
+            >
+              {labelText}
+            </Label>
+          )}
+          {fieldOutput}
+          {footnote && showHelperInvalidText && !isHidden && (
             <HelperErrorText
               id={`${id}-helperText`}
               isInvalid={isInvalid}
               text={footnote}
             />
-          </Box>
-        )}
-      </Box>
-    );
-  }
+          )}
+        </Box>
+      );
+    }
+  )
 );
 
 export default TextInput;