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

package/src/components/SearchBar/SearchBar.stories.mdx

@@ -60,7 +60,20 @@ import DSProvider from "../../theme/provider";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.0.4`    |
-| Latest            | `0.25.11`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [Form Components](#form-components)
+- [Search Autocomplete](#search-autocomplete)
+- [Form States](#form-states)
+- [With Heading and Description Text](#with-heading-and-description-text)
+- [TextInput and onSubmit Values](#textinput-and-onsubmit-values)
+
+## Overview
 
 <Description of={SearchBar} />
 
@@ -89,6 +102,8 @@ export const optionsGroup = [
   "Villagers",
 ];
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="SearchBar with Controls"
@@ -113,50 +128,75 @@ export const optionsGroup = [
       textInputProps: undefined,
     }}
   >
-    {(args) => (
-      <SearchBar
-        {...args}
-        selectProps={
-          args.showSelect && {
-            labelText: "Select a category",
-            name: "selectName",
-            optionsData: optionsGroup,
+    {(args) => {
+      const { helperText, showHelperText, showSelect, ...rest } = args;
+      return (
+        <SearchBar
+          {...rest}
+          selectProps={
+            showSelect && {
+              labelText: "Select a category",
+              name: "selectName",
+              optionsData: optionsGroup,
+            }
           }
-        }
-        textInputProps={{
-          labelText: "Item Search",
-          name: "textInputName",
-          placeholder: "Item Search",
-        }}
-        helperText={args.showHelperText && args.helperText}
-      />
-    )}
+          textInputProps={{
+            labelText: "Item Search",
+            name: "textInputName",
+            placeholder: "Item Search",
+          }}
+          helperText={showHelperText && helperText}
+        />
+      );
+    }}
   </Story>
 </Canvas>
 
 <ArgsTable story="SearchBar with Controls" />
 
-## Component Props
+## Accessibility
+
+The `SearchBar` component is implemented with Reservoir `Select`, `TextInput`,
+and `Button` accessible components. This a "complete" component that renders an
+HTML `<form>` element that is submitted with a `<button>` element of `type="submit"`.
+The `<form>` element also has a `role="search"` attribute that allows
+screenreaders to pick up this entire search form.
+
+Resources:
+
+- [Reservoir Select](https://nypl.github.io/nypl-design-system/storybook-static/?path=/docs/components-form-elements-select--select-with-controls)
+- [Reservoir TextInput](https://nypl.github.io/nypl-design-system/storybook-static/?path=/docs/components-form-elements-textinput--text-input-with-controls)
+- [a11ymatters Accessible Search Form](https://www.a11ymatters.com/pattern/accessible-search/)
+- [MDN ARIA: search role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/search_role)
+
+## Form Components
 
 ### Select Component
 
 To render an optional `Select` component, an object must be passed to the
 `selectProps` prop. It _must_ include `name`, `labelText`, and `optionsData`
-properties. The `onChange` property is optional. The `labelText` value won't be
-rendered but will be used for its `aria-label` attribute.
+properties. The `onChange` and `value` properties are optional. The `labelText`
+value won't be rendered but will be used for its `aria-label` attribute.
+
+If you want to control the `Select` component, you **must** pass the `onChange`
+and `value` props to the `selectProps` prop object. You must then control the
+state of the selected value in your application. See the example at end of this
+page for a full demonstration.
 
 ```
 const selectProps = {
-  name: "select-form-name",
   labelText: "Select a category",
-  optionsData: optionsGroup,
+  name: "select-form-name",
   onChange: (event) => {
     console.log(event.target.value);
   },
+  optionsData: optionsGroup,
+  value: "Art",
 };
 
 // ...
 <SearchBar
+  id="searchBar"
   onSubmit={() => {}}
   selectProps={selectProps}
   // ...
@@ -166,9 +206,9 @@ const selectProps = {
 ### TextInput Component
 
 To render the `TextInput` component, an object must be passed to the
-`textInputProps` prop. It _must_ include `labelText`, `name`, and `placeholder`
-properties. The `labelText` value won't be rendered but will be used for its
-`aria-label` attribute. Optional properties to pass include `onChange` and `value`.
+`textInputProps` prop. It _must_ include `labelText` and `name` properties. The
+`labelText` value won't be rendered but will be used for its `aria-label`
+attribute. Optional properties to pass include `onChange`, `placeholder`, and `value`.
 
 ```
 const textInputProps = {
@@ -183,6 +223,7 @@ const textInputProps = {
 
 // ...
 <SearchBar
+  id="searchBar"
   onSubmit={() => {}}
   textInputProps={textInputProps}
   // ...
@@ -200,6 +241,7 @@ const textInputElement = <CustomInput {...props} />;
 
 // ...
 <SearchBar
+  id="searchBar"
   onSubmit={() => {}}
   textInputElement={textInputElement}
   // ...
@@ -227,6 +269,7 @@ const helperText = "";
 
 // ...
 <SearchBar
+  id="searchBar"
   onSubmit={() => {}}
   helperText="Search for items in <b>Animal Crossing New Horizons</b>."
   // ...
@@ -238,6 +281,7 @@ const helperText = "";
     <SearchBar
       descriptionText="The helper text below contains HTML in a string."
       helperText="Search for items in <b>Animal Crossing New Horizons</b>."
+      id="helper-text"
       onSubmit={() => {}}
       textInputProps={{
         labelText: "Item Search",
@@ -248,6 +292,7 @@ const helperText = "";
     <br />
     <SearchBar
       descriptionText="The invalid text below contains HTML in a string."
+      id="invalid-text"
       isInvalid
       invalidText="Could <b>not</b> find the item <b>:(</b>"
       onSubmit={() => {}}
@@ -277,6 +322,7 @@ precedence.
   <Story
     name="Search Autocomplete"
     args={{
+      id: "autocomplete",
       isDisabled: false,
       isInvalid: false,
       isRequired: false,
@@ -295,7 +341,7 @@ precedence.
   </Story>
 </Canvas>
 
-## Other Examples
+## Form States
 
 Use the Controls in the `Basic` example to see different states in real time.
 Here are the same possible states of the `SearchBar` component in static examples.
@@ -309,15 +355,16 @@ handle the error state yourself.
 <Canvas>
   <DSProvider>
     <SearchBar
+      helperText="This is the helper text!"
+      id="error-state"
+      invalidText="Could not find the item :("
+      isInvalid
       onSubmit={() => {}}
       textInputProps={{
         labelText: "Item Search",
         name: "textInputName",
         placeholder: "Item Search",
       }}
-      helperText="This is the helper text!"
-      invalidText="Could not find the item :("
-      isInvalid
     />
   </DSProvider>
 </Canvas>
@@ -331,19 +378,20 @@ handle the disabled state yourself.
 <Canvas>
   <DSProvider>
     <SearchBar
+      helperText="Reason for disabled state."
+      id="disabled-state"
+      isDisabled
       onSubmit={() => {}}
       textInputProps={{
         labelText: "Item Search",
         name: "textInputName",
         placeholder: "Item Search",
       }}
-      helperText="Reason for disabled state."
-      isDisabled
     />
   </DSProvider>
 </Canvas>
 
-### With Heading and Description Text
+## With Heading and Description Text
 
 Use the `descriptionText` and `headingText` props to render a heading and
 description above the main `SearchBar` form component.
@@ -353,6 +401,7 @@ description above the main `SearchBar` form component.
     <SearchBar
       descriptionText="This is the description for this `SearchBar` instance."
       headingText="Heading for this `SearchBar`"
+      id="heading-and-description"
       onSubmit={() => {}}
       textInputProps={{
         labelText: "Item Search",
@@ -363,7 +412,7 @@ description above the main `SearchBar` form component.
   </DSProvider>
 </Canvas>
 
-### TextInput and onSubmit Values
+## TextInput and onSubmit Values
 
 _NOTE: open the browser console to see the values logged in the example below._
 
@@ -387,7 +436,12 @@ values can be retrieved as `event.target.selectName.value` and
 `event.target.textInputName.value`.
 
 ```tsx
-function SearchBarValueExample() {
+export function SearchBarValueExample() {
+  const [selectValue, setSelectValue] = React.useState("Tools");
+  const selectOnChange = (event) => {
+    console.log(`onChange Select value: ${event.target.value}`);
+    setSelectValue(event.target.value);
+  };
   const textInputOnChange = (event) => {
     console.log(`onChange TextInput value: ${event.target.value}`);
   };
@@ -398,11 +452,16 @@ function SearchBarValueExample() {
   };
   return (
     <SearchBar
+      helperText="Search for an item"
+      invalidText="Could not find the item :("
+      id="example-1"
       onSubmit={onSubmit}
       selectProps={{
         labelText: "Select a category",
         name: "selectName",
+        onChange: selectOnChange,
         optionsData: optionsGroup,
+        value: selectValue,
       }}
       textInputProps={{
         labelText: "Item Search",
@@ -410,14 +469,17 @@ function SearchBarValueExample() {
         onChange: textInputOnChange,
         placeholder: "Item Search",
       }}
-      helperText="Search for an item"
-      invalidText="Could not find the item :("
     />
   );
 }
 ```
 
 export function SearchBarValueExample() {
+  const [selectValue, setSelectValue] = React.useState("Tools");
+  const selectOnChange = (event) => {
+    console.log(`onChange Select value: ${event.target.value}`);
+    setSelectValue(event.target.value);
+  };
   const textInputOnChange = (event) => {
     console.log(`onChange TextInput value: ${event.target.value}`);
   };
@@ -428,11 +490,16 @@ export function SearchBarValueExample() {
   };
   return (
     <SearchBar
+      helperText="Search for an item"
+      invalidText="Could not find the item :("
+      id="example-1"
       onSubmit={onSubmit}
       selectProps={{
         labelText: "Select a category",
         name: "selectName",
+        onChange: selectOnChange,
         optionsData: optionsGroup,
+        value: selectValue,
       }}
       textInputProps={{
         labelText: "Item Search",
@@ -440,8 +507,6 @@ export function SearchBarValueExample() {
         onChange: textInputOnChange,
         placeholder: "Item Search",
       }}
-      helperText="Search for an item"
-      invalidText="Could not find the item :("
     />
   );
 }

package/src/components/SearchBar/{SearchBar.Test.tsx → SearchBar.test.tsx}

@@ -22,6 +22,7 @@ const selectProps: SelectProps = {
   name: "selectName",
   labelText: "Select a category",
   optionsData: optionsGroup,
+  value: "Songs",
 };
 const textInputProps: TextInputProps = {
   labelText: "Item Search",
@@ -162,7 +163,9 @@ describe("SearchBar", () => {
   });
 
   it("calls the Select onChange callback function", () => {
-    selectProps.onChange = jest.fn();
+    let selectValue = "Songs";
+    selectProps.onChange = (e) => (selectValue = e.target.value);
+    selectProps.value = selectValue;
 
     render(
       <SearchBar
@@ -175,13 +178,13 @@ describe("SearchBar", () => {
       />
     );
     const select = screen.getByLabelText(selectProps.labelText);
-    expect(selectProps.onChange).toHaveBeenCalledTimes(0);
+    expect(selectValue).toEqual("Songs");
 
     userEvent.selectOptions(select, "Flowers");
-    expect(selectProps.onChange).toHaveBeenCalledTimes(1);
+    expect(selectValue).toEqual("Flowers");
 
     userEvent.selectOptions(select, "Furniture");
-    expect(selectProps.onChange).toHaveBeenCalledTimes(2);
+    expect(selectValue).toEqual("Furniture");
   });
 
   it("calls the callback function for the Button component ", () => {
@@ -217,6 +220,25 @@ describe("SearchBar", () => {
     expect(searchBarSubmit).toHaveBeenCalledTimes(1);
   });
 
+  it("renders a default placeholder", () => {
+    const textInputProps: TextInputProps = {
+      labelText: "Item Search",
+      name: "textInputName",
+    };
+
+    render(
+      <SearchBar
+        id="requiredState"
+        isDisabled
+        labelText={labelText}
+        onSubmit={jest.fn()}
+        textInputProps={textInputProps}
+      />
+    );
+
+    expect(screen.getByPlaceholderText("Search terms")).toBeInTheDocument();
+  });
+
   it("renders 'required' in the placeholder text", () => {
     const { rerender } = render(
       <SearchBar
@@ -247,8 +269,19 @@ describe("SearchBar", () => {
     ).toBeInTheDocument();
   });
 
-  // TODO: Fix the `Select` component before enabling this test
-  it.skip("renders the UI snapshot correctly", () => {
+  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.
+      <SearchBar labelText={labelText} onSubmit={jest.fn()} />
+    );
+    expect(warn).toHaveBeenCalledWith(
+      "NYPL Reservoir SearchBar: This component's required `id` prop was not passed."
+    );
+  });
+
+  it("renders the UI snapshot correctly", () => {
     const basic = renderer
       .create(
         <SearchBar
@@ -360,6 +393,31 @@ describe("SearchBar", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <SearchBar
+          helperText={helperText}
+          id="chakra"
+          labelText={labelText}
+          onSubmit={jest.fn()}
+          textInputProps={textInputProps}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(
+        <SearchBar
+          helperText={helperText}
+          id="props"
+          labelText={labelText}
+          onSubmit={jest.fn()}
+          textInputProps={textInputProps}
+          data-testid="props"
+        />
+      )
+      .toJSON();
 
     expect(basic).toMatchSnapshot();
     expect(withSelect).toMatchSnapshot();
@@ -371,5 +429,7 @@ describe("SearchBar", () => {
     expect(withHeading).toMatchSnapshot();
     expect(withDescription).toMatchSnapshot();
     expect(withHeadingAndDescription).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/SearchBar/SearchBar.tsx

@@ -1,4 +1,4 @@
-import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+import { Box, chakra, useMultiStyleConfig } from "@chakra-ui/react";
 import * as React from "react";
 
 import Button from "../Button/Button";
@@ -11,8 +11,6 @@ import Select from "../Select/Select";
 import { SelectTypes } from "../Select/SelectTypes";
 import TextInput from "../TextInput/TextInput";
 import { TextInputTypes, TextInputVariants } from "../TextInput/TextInputTypes";
-import generateUUID from "../../helpers/generateUUID";
-
 interface BaseProps {
   labelText: string;
   name: string;
@@ -21,14 +19,14 @@ interface BaseProps {
       | React.ChangeEvent<HTMLInputElement>
       | React.ChangeEvent<HTMLTextAreaElement>
   ) => void;
+  value?: string;
 }
 // Internal interfaces that are used only for `SearchBar` props.
 export interface SelectProps extends BaseProps {
   optionsData: string[];
 }
 export interface TextInputProps extends BaseProps {
-  placeholder: string;
-  value?: string;
+  placeholder?: string;
 }
 
 export interface SearchBarProps {
@@ -45,7 +43,7 @@ export interface SearchBarProps {
   /** The text to display below the form in a `HelperErrorText` component. */
   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;
@@ -76,7 +74,7 @@ export interface SearchBarProps {
  * Renders a wrapper `form` element to be used with `Select` (optional),
  * `Input`, and `Button` components together.
  */
-export default function SearchBar(props: SearchBarProps) {
+export const SearchBar = chakra((props: SearchBarProps) => {
   const {
     action,
     buttonOnClick = null,
@@ -84,7 +82,7 @@ export default function SearchBar(props: SearchBarProps) {
     descriptionText,
     headingText,
     helperText,
-    id = generateUUID(),
+    id,
     invalidText,
     isDisabled = false,
     isInvalid = false,
@@ -96,6 +94,7 @@ export default function SearchBar(props: SearchBarProps) {
     selectProps,
     textInputElement,
     textInputProps,
+    ...rest
   } = props;
   const styles = useMultiStyleConfig("SearchBar", {});
   const stateProps = {
@@ -108,7 +107,8 @@ export default function SearchBar(props: SearchBarProps) {
   };
   const footnote = isInvalid ? invalidText : helperText;
   const finalAriaLabel = footnote ? `${labelText} - ${footnote}` : labelText;
-  const textInputPlaceholder = `${textInputProps?.placeholder} ${
+  const inputPlaceholder = textInputProps?.placeholder || "Search terms";
+  const textInputPlaceholder = `${inputPlaceholder} ${
     isRequired ? "(Required)" : ""
   }`;
   const buttonType = noBrandButtonType
@@ -120,6 +120,12 @@ export default function SearchBar(props: SearchBarProps) {
     lineHeight: "1.70",
     marginBottom: "auto",
   };
+
+  if (!id) {
+    console.warn(
+      "NYPL Reservoir SearchBar: This component's required `id` prop was not passed."
+    );
+  }
   // Render the `Select` component.
   const selectElem = selectProps && (
     <Select
@@ -128,7 +134,8 @@ export default function SearchBar(props: SearchBarProps) {
       labelText={selectProps?.labelText}
       name={selectProps?.name}
       onChange={selectProps?.onChange}
-      type={SelectTypes.SearchBar}
+      selectType={SelectTypes.SearchBar}
+      value={selectProps?.value}
       {...stateProps}
     >
       {selectProps?.optionsData.map((option) => (
@@ -146,12 +153,12 @@ export default function SearchBar(props: SearchBarProps) {
       name={textInputProps?.name}
       onChange={textInputProps?.onChange}
       placeholder={textInputPlaceholder}
-      type={TextInputTypes.text}
-      variantType={
+      textInputType={
         selectElem
           ? TextInputVariants.SearchBarSelect
           : TextInputVariants.SearchBar
       }
+      type={TextInputTypes.text}
       value={textInputProps?.value}
       {...stateProps}
     />
@@ -187,6 +194,7 @@ export default function SearchBar(props: SearchBarProps) {
       id={id}
       invalidText={invalidText}
       isInvalid={isInvalid}
+      {...rest}
     >
       <Box
         as="form"
@@ -205,4 +213,6 @@ export default function SearchBar(props: SearchBarProps) {
       </Box>
     </ComponentWrapper>
   );
-}
+});
+
+export default SearchBar;