@nypl/design-system-react-components 1.0.1 → 1.0.2

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

@@ -0,0 +1,518 @@
+import {
+  ArgsTable,
+  Canvas,
+  Description,
+  Meta,
+  Story,
+} from "@storybook/addon-docs";
+import { withDesign } from "storybook-addon-designs";
+
+import SearchBar from "./SearchBar";
+import * as stories from "../Autosuggest/Autosuggest.stories.tsx";
+import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
+
+<Meta
+  title={getCategory("SearchBar")}
+  component={SearchBar}
+  decorators={[withDesign]}
+  parameters={{
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=11689%3A423",
+    },
+    jest: ["SearchBar.test.tsx"],
+  }}
+  argTypes={{
+    action: { control: false },
+    ariaLabel: { control: false },
+    buttonOnClick: {
+      control: false,
+      table: { defaultValue: { summary: "null" } },
+    },
+    className: { control: false },
+    id: { control: false },
+    isDisabled: {
+      table: { defaultValue: { summary: false } },
+    },
+    isInvalid: {
+      table: { defaultValue: { summary: false } },
+    },
+    isRequired: {
+      table: { defaultValue: { summary: false } },
+    },
+    method: { control: false },
+    onSubmit: { control: false },
+    selectProps: { control: false },
+    showHelperText: {
+      description: "Only used for Storybook",
+    },
+    showSelect: {
+      description: "Only used for Storybook",
+    },
+    textInputElement: { control: false },
+    textInputProps: { control: false },
+  }}
+/>
+
+# SearchBar
+
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.0.4`    |
+| Latest            | `0.28.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} />
+
+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. 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.
+
+export const optionsGroup = [
+  "Art",
+  "Bushes",
+  "Clothing",
+  "Flowers",
+  "Fossils",
+  "Fruits",
+  "Furniture",
+  "Songs",
+  "Tools",
+  "Villagers",
+];
+
+## Component Props
+
+<Canvas withToolbar>
+  <Story
+    name="SearchBar with Controls"
+    args={{
+      action: undefined,
+      buttonOnClick: undefined,
+      className: undefined,
+      helperText: "Search for items in Animal Crossing New Horizons",
+      id: "searchBar-id",
+      invalidText: "Could not find the item :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+      labelText: "SearchBar Label",
+      method: undefined,
+      noBrandButtonType: false,
+      onSubmit: () => {},
+      selectProps: undefined,
+      showHelperText: true,
+      showSelect: true,
+      textInputElement: undefined,
+      textInputProps: undefined,
+    }}
+  >
+    {(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={showHelperText && helperText}
+        />
+      );
+    }}
+  </Story>
+</Canvas>
+
+<ArgsTable story="SearchBar with Controls" />
+
+## 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/reservoir/v1/?path=/docs/components-form-elements-select--select-with-controls)
+- [Reservoir TextInput](https://nypl.github.io/nypl-design-system/reservoir/v1/?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` 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 = {
+  labelText: "Select a category",
+  name: "select-form-name",
+  onChange: (event) => {
+    console.log(event.target.value);
+  },
+  optionsData: optionsGroup,
+  value: "Art",
+};
+
+// ...
+<SearchBar
+  id="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 `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 = {
+  labelText: "Item Search",
+  name: "textInputName",
+  onChange: (event) => {
+    console.log(event.target.value);
+  },
+  placeholder: "Item Search",
+  value: "Horizon"
+};
+
+// ...
+<SearchBar
+  id="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
+  id="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.
+
+It's also possible to render the `ButtonType.NoBrand` variant style when the
+`noBrandButtonType` prop is set to `true`. The `ButtonType.Primary` variant
+style is used by default.
+
+### HelperErrorText Component
+
+To render the `HelperErrorText` component, pass a string or HTML to the
+`helperText` prop. For the invalid state when `isInvalid` is true, pass the
+error string or HTML in the `invalidText` prop.
+
+```
+const helperText = "";
+
+// ...
+<SearchBar
+  id="searchBar"
+  onSubmit={() => {}}
+  helperText="Search for items in <b>Animal Crossing New Horizons</b>."
+  // ...
+/>
+```
+
+<Canvas>
+  <DSProvider>
+    <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",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+    />
+    <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={() => {}}
+      textInputProps={{
+        labelText: "Item Search",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+    />
+  </DSProvider>
+</Canvas>
+
+## 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/reservoir/v1/?path=/docs/development-guide-autosuggest--autosuggest-library)
+as the main component inside the `SearchBar` component.
+
+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={{
+      id: "autocomplete",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
+    }}
+  >
+    {(args) => (
+      <div style={{ minHeight: "150px" }}>
+        <SearchBar
+          onSubmit={() => {}}
+          textInputElement={stories.SearchBarExample()}
+          helperText="Select your home library. Start by typing the name of the library. Try 'ba'."
+          {...args}
+        />
+      </div>
+    )}
+  </Story>
+</Canvas>
+
+## 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.
+
+### Error State
+
+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.
+
+<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",
+      }}
+    />
+  </DSProvider>
+</Canvas>
+
+### Disabled State
+
+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.
+
+<Canvas>
+  <DSProvider>
+    <SearchBar
+      helperText="Reason for disabled state."
+      id="disabled-state"
+      isDisabled
+      onSubmit={() => {}}
+      textInputProps={{
+        labelText: "Item Search",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+    />
+  </DSProvider>
+</Canvas>
+
+## With Heading and Description Text
+
+Use the `descriptionText` and `headingText` props to render a heading and
+description above the main `SearchBar` form component.
+
+<Canvas>
+  <DSProvider>
+    <SearchBar
+      descriptionText="This is the description for this `SearchBar` instance."
+      headingText="Heading for this `SearchBar`"
+      id="heading-and-description"
+      onSubmit={() => {}}
+      textInputProps={{
+        labelText: "Item Search",
+        name: "textInputName",
+        placeholder: "Item Search",
+      }}
+    />
+  </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
+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}`);
+  };
+  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
+      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",
+        name: "textInputName",
+        onChange: textInputOnChange,
+        placeholder: "Item Search",
+      }}
+    />
+  );
+}
+```
+
+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}`);
+  };
+  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
+      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",
+        name: "textInputName",
+        onChange: textInputOnChange,
+        placeholder: "Item Search",
+      }}
+    />
+  );
+}
+
+<Canvas>
+  <DSProvider>
+    <SearchBarValueExample />
+  </DSProvider>
+</Canvas>