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

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

@@ -1,518 +0,0 @@
-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>