@nypl/design-system-react-components 0.25.0 → 0.25.1

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

@@ -2,20 +2,12 @@ import {
   Meta,
   Story,
   ArgsTable,
-  Preview,
+  Canvas,
   Description,
 } from "@storybook/addon-docs/blocks";
 import { withDesign } from "storybook-addon-designs";
 
 import SearchBar from "./SearchBar";
-import Select from "../Select/Select";
-import HelperErrorText from "../HelperErrorText/HelperErrorText";
-import Button from "../Button/Button";
-import { ButtonTypes } from "../Button/ButtonTypes";
-import Icon from "../Icons/Icon";
-import { IconNames } from "../Icons/IconTypes";
-import Input from "../Input/Input";
-import { InputTypes } from "../Input/InputTypes";
 import * as stories from "../Autosuggest/Autosuggest.stories.tsx";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
@@ -33,9 +25,16 @@ import DSProvider from "../../theme/provider";
     jest: ["SearchBar.test.tsx"],
   }}
   argTypes={{
-    blockName: {
-      table: { disable: true },
-    },
+    action: { table: { disable: true } },
+    ariaLabel: { table: { disable: true } },
+    buttonOnClick: { table: { disable: true } },
+    className: { table: { disable: true } },
+    id: { table: { disable: true } },
+    method: { table: { disable: true } },
+    onSubmit: { table: { disable: true } },
+    selectProps: { table: { disable: true } },
+    textInputProps: { table: { disable: true } },
+    textInputElement: { table: { disable: true } },
   }}
 />
 
@@ -43,178 +42,183 @@ import DSProvider from "../../theme/provider";
 
 <Description of={SearchBar} />
 
-The main wrapper element that is rendered is `<form>` DOM element. All the props
-passed to `SearchBar` will apply to the `<form>` element. If you need to update
-the children, make sure the props are passed to the appropriate components.
+The main wrapper element that is rendered is a `<form>` DOM element. All the
+props passed to `SearchBar` will apply to the `<form>` element and its children.
+The `SearchBar` component will render a `Select` component (optional),
+`TextInput` component, `Button` component, and `HelperErrorText` component
+based on the required props.
 
 The `Select` dropdown narrows the search within a specific category, typically
-title or author. You should only have one `Select` component at a time. If you
-need more options, link to the advance search page. Toggle the `Select` through
-the Controls.
-
-_Note: The `HelperErrorText` component should be the next direct sibling of the
-`SearchBar` component if it will be used._
-
-export const optionsGroup = {
-  Art: [
-    "Academic Painting",
-    "Amazing Painting",
-    "Ancient Statue",
-    "Basic Painting",
-    "Beautiful Statue",
-  ],
-  Bushes: [
-    "Blue-Hydrangea Bush",
-    "Blue-Hydrangea Start",
-    "Holly Bush",
-    "Orange-Tea-Olive Bush",
-    "Pink Camellia Bush",
-  ],
-  Clothing: ["3D Glasses", "Academy Uniform", "Acid-Washed Jacket"],
-  "DIY Recipes": ["Acorn Pochette", "Acoustic Guitar", "Angled Signpost"],
-  Flowers: [
-    "Black Cosmos",
-    "Blue Pansies",
-    "Gold Roses",
-    "Lily of the Valley",
-    "Orange Hyacinth",
-  ],
-  Fossils: [
-    "Acanthostega",
-    "Amber",
-    "Ammonite",
-    "Ankylo Skull",
-    "Anomalocaris",
-    "Australopith",
-  ],
-  Fruits: ["Apples", "Oranges", "Pears", "Coconuts", "Cherries"],
-  Furniture: [
-    "Abstract Wall",
-    "Accessories Stand",
-    "ACNH Switch",
-    "Air Circulator",
-  ],
-  Materials: [
-    "Acorn",
-    "Aquaris Fragment",
-    "Bamboo Piece",
-    "Boot",
-    "Clump of Weeds",
-  ],
-  NPC: ["Celeste", "Kicks", "Leif", "Redd", "Saharah"],
-  Songs: ["Agent K.K.", "Café K.K.", "Comrade K.K."],
-  Tools: [
-    "Axe",
-    "Bamboo Wand",
-    "Fishing Rod",
-    "Shovel",
-    "Slingshot",
-    "Watering Can",
-  ],
-  Villagers: ["Agnes", "Alfonso", "Anchovy", "Axel", "Aurora"],
-};
+title or author. Toggle the `Select` through the Controls.
+
+export const optionsGroup = [
+  "Art",
+  "Bushes",
+  "Clothing",
+  "Flowers",
+  "Fossils",
+  "Fruits",
+  "Furniture",
+  "Songs",
+  "Tools",
+  "Villagers",
+];
 
-<Preview withToolbar>
+<Canvas withToolbar>
   <Story
     name="Basic"
     args={{
       showHelperText: true,
       showSelect: true,
-      isErrorState: false,
-      disabledButton: false,
+      invalidText: "Could not find the item :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      helperErrorText: "Search for items in Animal Crossing New Horizons",
     }}
   >
     {(args) => (
-      <div>
-        <SearchBar {...args}>
-          {args.showSelect && (
-            <Select
-              name="nhItemSearch"
-              ariaLabel="Filter Search"
-              id="select-searchBar"
-              isRequired={false}
-            >
-              {Object.keys(optionsGroup).map((nhOption) => (
-                <option key={nhOption} aria-selected={false}>
-                  {nhOption}
-                </option>
-              ))}
-            </Select>
-          )}
-          <Input
-            id="inputBasic"
-            ariaLabelledBy="buttonBasic"
-            placeholder="Item Search"
-            required={true}
-            type={InputTypes.text}
-            attributes={{
-              ["aria-describedby"]: "helperTextBasic",
-            }}
-            errored={args.isErrorState}
-          />
-          <Button
-            buttonType={ButtonTypes.Primary}
-            id="buttonBasic"
-            type="submit"
-            disabled={args.disabledButton}
-          >
-            <Icon
-              name={IconNames.search}
-              decorative={true}
-              modifiers={["small", "icon-left"]}
-            />
-            Search
-          </Button>
-        </SearchBar>
-        {args.showHelperText && (
-          <HelperErrorText id="helperTextBasic" isError={args.isErrorState}>
-            Search for items in Animal Crossing New Horizons
-          </HelperErrorText>
-        )}
-      </div>
+      <SearchBar
+        onSubmit={() => {}}
+        {...args}
+        selectProps={
+          args.showSelect && {
+            name: "nhItemSearch",
+            labelText: "Select a category",
+            optionsData: optionsGroup,
+          }
+        }
+        textInputProps={{
+          labelText: "Item Search",
+          placeholder: "Item Search",
+        }}
+        helperErrorText={args.showHelperText && args.helperErrorText}
+      />
     )}
   </Story>
-</Preview>
+</Canvas>
 
 <ArgsTable story="Basic" />
 
+## Component Props
+
+### 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 `labelText` value won't be rendered but will be used for its
+`aria-label` attribute.
+
+```
+const selectProps = {
+  name: "select-form-name",
+  labelText: "Select a category",
+  optionsData: optionsGroup,
+};
+
+// ...
+<SearchBar
+  onSubmit={() => {}}
+  selectProps={selectProps}
+  // ...
+/>
+```
+
+### TextInput Component
+
+To render the `TextInput` component, an object must be passed to the
+`textInputProps` prop. It _must_ include `labelText` and `placeholder`
+properties. The `labelText` value won't be rendered but will be used for its
+`aria-label` attribute.
+
+```
+const textInputProps = {
+  labelText: "Item Search",
+  placeholder: "Item Search",
+};
+
+// ...
+<SearchBar
+  onSubmit={() => {}}
+  textInputProps={textInputProps}
+  // ...
+/>
+```
+
+### Custom Input Component
+
+To render a custom input component, pass the component to the `textInputElement`
+prop. This will render your custom input component such as an `Autocomplete`
+component. Check the "Search Autocomplete" example for more details.
+
+```
+const textInputElement = <CustomInput {...props} />;
+
+// ...
+<SearchBar
+  onSubmit={() => {}}
+  textInputElement={textInputElement}
+  // ...
+/>
+```
+
+### Button Component
+
+A `Button` component will automatically be rendered for the `SearchBar`
+component. If you want to pass a callback function to the `Button`, use the
+`buttonOnClick` prop.
+
+### HelperErrorText Component
+
+To render the `HelperErrorText` component, pass a string value to the
+`helperErrorText` prop. For the invalid state when `isInvalid` is true, pass the
+error string in the `invalidText` prop.
+
+```
+const helperErrorText = "";
+
+// ...
+<SearchBar
+  onSubmit={() => {}}
+  helperErrorText="Search for items in Animal Crossing New Horizons"
+  // ...
+/>
+```
+
 ## Search Autocomplete
 
 While the Design System does not implement an `Autosuggest` or `Autocomplete`
 component, it does show a pattern for using the `react-autosuggest` package.
 In this example, we're using the `react-autosuggest` example found in the
 [Basic Autosuggest story](https://nypl.github.io/nypl-design-system/storybook-static/?path=/story/autosuggest--autosuggest-library)
-as the main component inside the `SearchBar` component. See the combination of
-the Autosuggest story along with this story to see how to compose all the
-components together.
+as the main component inside the `SearchBar` component.
 
-<Preview withToolbar>
-  <Story name="Search Autocomplete">
+In order to render this custom input element in the `SearchBar` component, pass
+it in the `textInputElement` prop. Do not pass an object to the `textInputProps`
+prop since the custom input component passed in `textInputElement` will take
+precedence.
+
+<Canvas withToolbar>
+  <Story
+    name="Search Autocomplete"
+    args={{
+      isInvalid: false,
+      isDisabled: false,
+      isRequired: false,
+    }}
+  >
     {(args) => (
       <div style={{ minHeight: "150px" }}>
-        <SearchBar {...args}>
-          {stories.SearchBarExample()}
-          <Button
-            buttonType={ButtonTypes.Primary}
-            id="autosuggest-button"
-            type="submit"
-          >
-            <Icon
-              name={IconNames.search}
-              decorative={true}
-              modifiers={["small", "icon-left"]}
-            />
-            Search
-          </Button>
-        </SearchBar>
-        <HelperErrorText id="autosuggest-helperText" isError={false}>
-          Select your home library. Start by typing the name of the library. Try{" "}
-          {'"'}ba{'"'}.
-        </HelperErrorText>
+        <SearchBar
+          onSubmit={() => {}}
+          textInputElement={stories.SearchBarExample()}
+          helperErrorText="Select your home library. Start by typing the name of the library. Try 'ba'."
+          {...args}
+        />
       </div>
     )}
   </Story>
-</Preview>
+</Canvas>
 
 ## Other Examples
 
@@ -223,75 +227,41 @@ Here are the same possible states of the `SearchBar` component in static example
 
 ### Error State
 
-For the error state, make sure that the `errored` prop is passed to the `Input`
-component and the `isError` prop is passed to the `HelperErrorText` component.
+For the error state, set the `isInvalid` prop to `true`. This will update the
+state for all its children. If you passed a custom input element, you must
+handle the error state yourself.
 
-<Preview>
+<Canvas>
   <DSProvider>
-    <SearchBar>
-      <Input
-        ariaLabelledBy="button-error-state"
-        id="input-error"
-        placeholder="Item Search"
-        required={true}
-        type={InputTypes.text}
-        errored={true}
-        attributes={{
-          ["aria-describedby"]: "error-helperText",
-        }}
-      />
-      <Button
-        buttonType={ButtonTypes.Primary}
-        id="button-error-state"
-        type="submit"
-      >
-        <Icon
-          name={IconNames.search}
-          decorative={true}
-          modifiers={["small", "icon-left"]}
-        />
-        Search
-      </Button>
-    </SearchBar>
-    <HelperErrorText id="error-helperText" isError={true}>
-      Sorry, we can't find that item!
-    </HelperErrorText>
+    <SearchBar
+      onSubmit={() => {}}
+      textInputProps={{
+        labelText: "Item Search",
+        placeholder: "Item Search",
+      }}
+      helperErrorText="Sorry, we can't find that item!"
+      invalidText="Could not find the item :("
+      isInvalid
+    />
   </DSProvider>
-</Preview>
-
-<br />
+</Canvas>
 
 ### Disabled State
 
-For the disabled state, make sure to pass the `disabled` prop to the
-`Button` component.
+For the disabled state, set the `isDisabled` prop to `true`. This will update
+the state for all its children. If you passed a custom input element, you must
+handle the disabled state yourself.
 
-<Preview>
+<Canvas>
   <DSProvider>
-    <SearchBar>
-      <Input
-        ariaLabelledBy="button-disabled"
-        id="input-disabled"
-        placeholder="Item Search"
-        required={true}
-        type={InputTypes.text}
-      />
-      <Button
-        buttonType={ButtonTypes.Primary}
-        id="button-disabled"
-        type="submit"
-        disabled={true}
-      >
-        <Icon
-          name={IconNames.search}
-          decorative={true}
-          modifiers={["small", "icon-left"]}
-        />
-        Search
-      </Button>
-    </SearchBar>
-    <HelperErrorText id="error-disabled">
-      Reason for disabled state.
-    </HelperErrorText>
+    <SearchBar
+      obSubmit={() => {}}
+      textInputProps={{
+        labelText: "Item Search",
+        placeholder: "Item Search",
+      }}
+      helperErrorText="Reason for disabled state."
+      isDisabled
+    />
   </DSProvider>
-</Preview>
+</Canvas>

package/src/components/SearchBar/SearchBar.tsx

@@ -1,69 +1,174 @@
 import * as React from "react";
-import bem from "../../utils/bem";
+import { Box, useMultiStyleConfig } from "@chakra-ui/react";
+
+import generateUUID from "../../helpers/generateUUID";
+import Select from "../Select/Select";
+import TextInput from "../TextInput/TextInput";
+import { TextInputTypes, TextInputVariants } from "../TextInput/TextInputTypes";
+import Button from "../Button/Button";
+import { ButtonTypes } from "../Button/ButtonTypes";
+import Icon from "../Icons/Icon";
+import { IconAlign, IconNames, IconSizes } from "../Icons/IconTypes";
+import HelperErrorText from "../HelperErrorText/HelperErrorText";
+import { SelectTypes } from "../Select/SelectTypes";
+
+// Internal interfaces that are used only for `SearchBar` props.
+interface SelectProps {
+  labelText: string;
+  name: string;
+  optionsData: string[];
+}
+interface TextInputProps {
+  labelText: string;
+  placeholder: string;
+}
 
 export interface SearchBarProps {
-  /** Populates aria-label on the form;
-   * defines a hidden string that labels
-   * the SearchBar
-   */
-  ariaLabel?: string;
-  /** Populates aria-labelledby on the form;
-   * defines a visible string that labels
-   * the SearchBar
-   */
-  ariaLabelledBy?: string;
-  /** Additional attributes passed to the form */
-  attributes?: { [key: string]: any };
-  /** BlockName for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  blockName?: string;
-  /** ClassName that appears in addition to "search-bar" */
-  className?: string;
-  /** Adds 'method' property to the form */
-  method?: string;
-  /** Adds 'action' property to the form */
+  /** Adds 'action' property to the `form` element. */
   action?: string;
+  /** The onClick callback function for the `Button` component. */
+  buttonOnClick?: (event: React.MouseEvent | React.KeyboardEvent) => void;
+  /** A class name for the `form` element. */
+  className?: string;
+  /** The text to display below the form in a `HelperErrorText` component. */
+  helperErrorText?: string;
   /** ID that other components can cross reference for accessibility purposes */
   id?: string;
-  /** Modifiers array for use with BEM. See how to work with modifiers and BEM here: http://getbem.com/introduction/ */
-  modifiers?: string[];
-  /** Handler on form submit */
+  /** Optional string to populate the `HelperErrorText` for the error state
+   * when `isInvalid` is true. */
+  invalidText?: string;
+  /** Sets children form components in the disabled state. */
+  isDisabled?: boolean;
+  /** Sets children form components in the error state. */
+  isInvalid?: boolean;
+  /** Sets children form components in the required state. */
+  isRequired?: boolean;
+  /** Populates the `aria-label` attribute on the form element. */
+  labelText: string;
+  /** Adds 'method' property to the `form` element. */
+  method?: string;
+  /** Handler function when the form is submitted. */
   onSubmit: (event: React.FormEvent) => void;
+  /** Required props to render a `Select` element. */
+  selectProps?: SelectProps | undefined;
+  /** Will be used to visually display the label text for this
+   * `SearchBar` component. False by default. */
+  showLabel?: boolean;
+  /** Custom input element to render instead of a `TextInput` element. */
+  textInputElement?: JSX.Element;
+  /** Required props to render a `TextInput` element. */
+  textInputProps?: TextInputProps | undefined;
 }
 
-/** Renders a wrapper `form` element to be used with `Select` (optional),
- * `Input`, and `Button` components together. */
-export default function SearchBar(
-  props: React.PropsWithChildren<SearchBarProps>
-) {
+/**
+ * Renders a wrapper `form` element to be used with `Select` (optional),
+ * `Input`, and `Button` components together.
+ */
+export default function SearchBar(props: SearchBarProps) {
   const {
-    ariaLabel,
-    ariaLabelledBy,
-    blockName,
-    children,
+    action,
+    buttonOnClick = null,
     className,
-    id,
-    modifiers = [],
-    onSubmit,
-    attributes,
+    helperErrorText,
+    id = generateUUID(),
+    invalidText,
+    isDisabled = false,
+    isInvalid = false,
+    isRequired = false,
+    labelText,
     method,
-    action,
+    onSubmit,
+    selectProps,
+    textInputElement,
+    textInputProps,
   } = props;
-
-  const baseClass = "search-bar";
+  const styles = useMultiStyleConfig("SearchBar", { hasSelect: selectProps });
+  const stateProps = { isDisabled, isInvalid, isRequired };
+  const helperErrorTextID = generateUUID();
+  const ariaDescribedby = helperErrorTextID;
+  const footnote = isInvalid ? invalidText : helperErrorText;
+  const finalAriaLabel = footnote ? `${labelText} - ${footnote}` : labelText;
+  // Render the `Select` component.
+  const selectElem = selectProps && (
+    <Select
+      id={generateUUID()}
+      name={selectProps?.name}
+      labelText={selectProps?.labelText}
+      showLabel={false}
+      helperText=""
+      type={SelectTypes.SearchBar}
+      {...stateProps}
+    >
+      {selectProps?.optionsData.map((option) => (
+        <option key={option} value={option}>
+          {option}
+        </option>
+      ))}
+    </Select>
+  );
+  // Render the `TextInput` component.
+  const textInputNative = textInputProps && (
+    <TextInput
+      id={generateUUID()}
+      labelText={textInputProps?.labelText}
+      placeholder={textInputProps?.placeholder}
+      type={TextInputTypes.text}
+      variantType={
+        selectElem
+          ? TextInputVariants.SearchBarSelect
+          : TextInputVariants.SearchBar
+      }
+      helperText=""
+      showLabel={false}
+      {...stateProps}
+    />
+  );
+  // Render the `Button` component.
+  const buttonElem = (
+    <Button
+      id={generateUUID()}
+      buttonType={ButtonTypes.SearchBar}
+      type="submit"
+      onClick={buttonOnClick}
+      disabled={isDisabled}
+    >
+      <Icon
+        name={IconNames.Search}
+        size={IconSizes.Small}
+        align={IconAlign.Left}
+      />
+      Search
+    </Button>
+  );
+  // Render the `HelperErrorText` component.
+  const helperErrorTextElem = footnote && (
+    <HelperErrorText id={helperErrorTextID} isError={isInvalid}>
+      {footnote}
+    </HelperErrorText>
+  );
+  // If a custom input element was passed, use that instead of the
+  // `TextInput` component.
+  const textInputElem = textInputElement || textInputNative;
 
   return (
-    <form
-      className={bem(baseClass, modifiers, blockName, [className])}
+    <Box
+      as="form"
       id={id}
+      className={className}
       role="search"
-      aria-label={ariaLabel}
-      aria-labelledby={ariaLabelledBy}
+      aria-label={finalAriaLabel}
+      aria-describedby={ariaDescribedby}
       onSubmit={onSubmit}
       method={method}
       action={action}
-      {...attributes}
+      __css={styles}
     >
-      {children}
-    </form>
+      <Box __css={styles.topRow}>
+        {selectElem}
+        {textInputElem}
+        {buttonElem}
+      </Box>
+      {helperErrorTextElem}
+    </Box>
   );
 }