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

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,188 +25,214 @@ 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 } },
   }}
 />
 
 # SearchBar
 
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `0.25.4`   |
+
 <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.
+
+Note: The labels for the `Select` and `TextInput` components are not visible but
+aria-labels are used to make these children components accessible.
 
-<Preview withToolbar>
+export const optionsGroup = [
+  "Art",
+  "Bushes",
+  "Clothing",
+  "Flowers",
+  "Fossils",
+  "Fruits",
+  "Furniture",
+  "Songs",
+  "Tools",
+  "Villagers",
+];
+
+<Canvas withToolbar>
   <Story
     name="Basic"
     args={{
+      helperErrorText: "Search for items in Animal Crossing New Horizons",
+      invalidText: "Could not find the item :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
       showHelperText: true,
       showSelect: true,
-      isErrorState: false,
-      disabledButton: false,
     }}
   >
     {(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 && {
+            labelText: "Select a category",
+            name: "selectName",
+            optionsData: optionsGroup,
+          }
+        }
+        textInputProps={{
+          labelText: "Item Search",
+          name: "textInputName",
+          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`, `name`, and `placeholder`
+properties. The `labelText` value won't be rendered but will be used for its
+`aria-label` attribute. Optional values to pass include `onChange` and `value`.
+
+```
+const textInputProps = {
+  labelText: "Item Search",
+  name: "textInputName",
+  onChange: (event) => {
+    console.log(event.target.value);
+  },
+  placeholder: "Item Search",
+  value: "Horizon"
+};
+
+// ...
+<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={{
+      isDisabled: false,
+      isInvalid: 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 +241,132 @@ 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",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+      helperErrorText="This is the helper text!"
+      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",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+      helperErrorText="Reason for disabled state."
+      isDisabled
+    />
+  </DSProvider>
+</Canvas>
+
+### TextInput and onSubmit Values
+
+_NOTE: open the browser console to see the values logged in the example below._
+
+It is possible to get certain values from the `SearchBar` component by passing
+callback functions as props.
+
+The keyword value in the `TextInput` component can be accessed by passing a
+function to the `onChange` property in the `textInputProp` prop. This is useful
+for validating the keyword the user entered.
+
+To get values when the form is submitted, you must:
+
+- pass values for the `name` property in the `selectProps` and `textInputProps`
+  prop objects.
+- get the values returned in the `onSubmit` callback function.
+
+In the following example, the `name` for the `Select` is "selectName" and the
+`name` for the `TextInput` is "textInputName". The `onSubmit` function can get
+the submitted values through the `event` object. In the example below, the
+values can be retrieved as `event.target.selectName.value` and
+`event.target.textInputName.value`.
+
+```tsx
+function SearchBarValueExample() {
+  const textInputOnChange = (event) => {
+    console.log(`onChange TextInput value: ${event.target.value}`);
+  };
+  const onSubmit = (event) => {
+    event.preventDefault();
+    console.log(`onSubmit Select value: ${event.target.searchName.value}`);
+    console.log(`onSubmit TextInput value ${event.target.textInputName.value}`);
+  };
+  return (
+    <SearchBar
+      onSubmit={onSubmit}
+      selectProps={{
+        labelText: "Select a category",
+        name: "selectName",
+        optionsData: optionsGroup,
+      }}
+      textInputProps={{
+        labelText: "Item Search",
+        name: "textInputName",
+        onChange: textInputOnChange,
+        placeholder: "Item Search",
+      }}
+      helperErrorText="Search for an item"
+      invalidText="Could not find the item :("
+    />
+  );
+}
+```
+
+export function SearchBarValueExample() {
+  const textInputOnChange = (event) => {
+    console.log(`onChange TextInput value: ${event.target.value}`);
+  };
+  const onSubmit = (event) => {
+    event.preventDefault();
+    console.log(`onSubmit Select value: ${event.target.selectName.value}`);
+    console.log(`onSubmit TextInput value ${event.target.textInputName.value}`);
+  };
+  return (
+    <SearchBar
+      onSubmit={onSubmit}
+      selectProps={{
+        labelText: "Select a category",
+        name: "selectName",
+        optionsData: optionsGroup,
+      }}
+      textInputProps={{
+        labelText: "Item Search",
+        name: "textInputName",
+        onChange: textInputOnChange,
+        placeholder: "Item Search",
+      }}
+      helperErrorText="Search for an item"
+      invalidText="Could not find the item :("
+    />
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SearchBarValueExample />
   </DSProvider>
-</Preview>
+</Canvas>