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

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

@@ -41,18 +41,18 @@ 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,
+      table: { defaultValue: { summary: "TextInputVariants.Default" } },
+    },
     type: {
       control: { type: "select" },
       table: { defaultValue: { summary: "TextInputTypes.text" } },
       options: enumValues.options,
     },
     value: { control: false },
-    variantType: {
-      control: false,
-      table: { defaultValue: { summary: "TextInputVariants.Default" } },
-    },
   }}
 />
 
@@ -61,7 +61,18 @@ export const enumValues = getStorybookEnumValues(
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.22.0`   |
-| Latest            | `0.25.11`  |
+| 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,11 +104,11 @@ 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,
-      variantType: TextInputVariants.Default,
+      textInputType: TextInputVariants.Default,
     }}
   >
     {(args) => <TextInput {...args} type={enumValues.getValue(args.type)} />}
@@ -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>
@@ -206,14 +251,15 @@ helperText={<>Choose <b>wisely!</b></>}
 ## Textarea
 
 The TextInput component includes a multiline `textarea` form field. To render a
-`textarea` element, pass `TextInputTypes.textarea` for the `type` prop. All the
-variations described above are available for the `textarea` option.
+`textarea` element, pass `TextInputTypes.textarea` for the `type` prop.
+All the variations described above are available for the `textarea` option.
 
 <Canvas withToolbar>
   <Story
     name="Textarea"
     args={{
       helperText: "Let it all out.",
+      id: "textarea",
       invalidText: "This is error text :(",
       isDisabled: false,
       isInvalid: false,
@@ -221,12 +267,12 @@ 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={{
       type: { control: false },
-      variantType: { control: false },
+      textInputType: { control: false },
     }}
   >
     {(args) => <TextInput {...args} />}

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

@@ -6,17 +6,17 @@ 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
-        labelText="Custom input label"
+        id="textInput"
         isRequired
+        labelText="Custom input label"
+        onChange={jest.fn()}
         placeholder="Input Placeholder"
         type={TextInputTypes.text}
-        onChange={jest.fn()}
       />
     );
     expect(await axe(container)).toHaveNoViolations();
@@ -25,11 +25,12 @@ describe("TextInput Accessibility", () => {
   it("passes axe accessibility test for the textarea element", async () => {
     const { container } = render(
       <TextInput
-        labelText="Custom textarea label"
+        id="textInput"
         isRequired
+        labelText="Custom textarea label"
+        onChange={jest.fn()}
         placeholder="Input Placeholder"
         type={TextInputTypes.textarea}
-        onChange={jest.fn()}
       />
     );
     expect(await axe(container)).toHaveNoViolations();
@@ -46,13 +47,13 @@ describe("TextInput", () => {
     changeHandler = jest.fn();
     utils = render(
       <TextInput
+        attributes={{ onFocus: focusHandler }}
         id="myTextInput"
-        labelText="Custom Input Label"
         isRequired
+        labelText="Custom Input Label"
+        onChange={changeHandler}
         placeholder="Input Placeholder"
         type={TextInputTypes.text}
-        attributes={{ onFocus: focusHandler }}
-        onChange={changeHandler}
       />
     );
   });
@@ -70,34 +71,17 @@ describe("TextInput", () => {
     expect(screen.getByText(/Required/i)).toBeInTheDocument();
   });
 
-  it("renders 'Optional' along with the label text", () => {
+  it("does not render '(Required)' along with the label text", () => {
     utils.rerender(
       <TextInput
-        id="myTextInput"
-        labelText="Custom Input Label"
-        isRequired={false}
-        placeholder="Input Placeholder"
-        type={TextInputTypes.text}
         attributes={{ onFocus: focusHandler }}
-        onChange={changeHandler}
-      />
-    );
-
-    expect(screen.getByText("Custom Input Label")).toBeInTheDocument();
-    expect(screen.getByText(/Optional/i)).toBeInTheDocument();
-  });
-
-  it("does not render 'Required' along with the label text", () => {
-    utils.rerender(
-      <TextInput
         id="myTextInput"
-        labelText="Custom Input Label"
         isRequired
-        showOptReqLabel={false}
+        labelText="Custom Input Label"
+        onChange={changeHandler}
         placeholder="Input Placeholder"
+        showRequiredLabel={false}
         type={TextInputTypes.text}
-        attributes={{ onFocus: focusHandler }}
-        onChange={changeHandler}
       />
     );
 
@@ -136,20 +120,30 @@ 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
-        labelText="Custom Input Label"
-        showLabel={false}
         helperText="Custom Helper Text"
+        id="textInput"
         isRequired
+        labelText="Custom Input Label"
         placeholder="Input Placeholder"
+        showLabel={false}
         type={TextInputTypes.text}
       />
     );
@@ -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();
   });
@@ -185,12 +174,12 @@ describe("TextInput shows error state", () => {
   beforeEach(() => {
     const utils = render(
       <TextInput
-        id="myTextInputError"
-        labelText="Custom Input Label"
         helperText="Custom Helper Text"
+        id="myTextInputError"
         invalidText="Custom Error Text"
-        placeholder="Input Placeholder"
         isInvalid
+        labelText="Custom Input Label"
+        placeholder="Input Placeholder"
         type={TextInputTypes.text}
       />
     );
@@ -214,14 +203,14 @@ describe("TextInput shows error state", () => {
   it("does not render the invalid text when 'showHelperInvalidText' is set to false", () => {
     rerender(
       <TextInput
-        id="myTextInputError"
-        labelText="Custom Input Label"
         helperText="Custom Helper Text"
+        id="myTextInputError"
         invalidText="Custom Error Text"
+        isInvalid
+        labelText="Custom Input Label"
         placeholder="Input Placeholder"
         showHelperInvalidText={false}
         type={TextInputTypes.text}
-        isInvalid
       />
     );
     expect(screen.queryByText("Custom Helper Text")).not.toBeInTheDocument();
@@ -241,16 +230,16 @@ describe("Renders HTML attributes passed through the `attributes` prop", () => {
   beforeEach(() => {
     render(
       <TextInput
-        id="inputID-attributes"
-        labelText="Input Label"
-        placeholder="Input Placeholder"
-        type={TextInputTypes.text}
         attributes={{
           onChange: onChangeSpy,
           onBlur: onBlurSpy,
           maxLength: 10,
           tabIndex: 0,
         }}
+        id="inputID-attributes"
+        labelText="Input Label"
+        placeholder="Input Placeholder"
+        type={TextInputTypes.text}
       />
     );
   });
@@ -336,9 +325,9 @@ describe("Hidden input", () => {
   it("does not show the helper text", () => {
     render(
       <TextInput
+        helperText="Helper Text"
         id="inputID-hidden"
         labelText="Hidden Input Label"
-        helperText="Helper Text"
         type={TextInputTypes.hidden}
         value="hidden"
       />
@@ -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,7 +460,10 @@ 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", () => {
     const basicTextarea = renderer
       .create(