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

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>
   );
 }

package/src/components/Select/Select.stories.mdx

@@ -3,16 +3,14 @@ import {
   Story,
   Canvas,
   ArgsTable,
-  Preview,
   Description,
 } from "@storybook/addon-docs/blocks";
 import { withDesign } from "storybook-addon-designs";
 
+import { VStack } from "@chakra-ui/react";
 import Select from "./Select";
-import Label from "../Label/Label";
-import HelperErrorText from "../HelperErrorText/HelperErrorText";
-import { action } from "@storybook/addon-actions";
 import { getCategory } from "../../utils/componentCategories";
+import DSProvider from "../../theme/provider";
 
 <Meta
   title={getCategory("Select")}
@@ -27,203 +25,230 @@ import { getCategory } from "../../utils/componentCategories";
     jest: ["Select.test.tsx"],
   }}
   argTypes={{
-    blockName: { table: { disable: true } },
-    className: { table: { disable: true } },
-    modifiers: { table: { disable: true } },
-    attributes: { table: { disable: true } },
+    children: { table: { disable: true } },
+    id: { table: { disable: true } },
+    name: { table: { disable: true } },
+    onChange: { table: { disable: true } },
+    value: { table: { disable: true } },
   }}
 />
 
 # Select
 
-<Description of={Select} />
+| Component Version | DS Version |
+| ----------------- | ---------- |
+| Added             | `0.7.0`    |
+| Latest            | `0.25.1`   |
 
-The `Select` component renders a `select` element along with its `option` children. For optimal accessibility, the `labelText` property is a required prop, regardless of the label visibility. Additionally, while the `id` prop is optional, a unique `id` attribute is necessary for accessibility. If the prop is left blank, a value will be generated for you.
+<Description of={Select} />
 
-<Preview withToolbar>
+The `Select` component renders a `select` element along with its `option`
+children. For optimal accessibility, the `labelText` property is a required
+prop, regardless of the label visibility. Additionally, while the `id` prop is
+optional, a unique `id` attribute is necessary for accessibility. If the prop
+is left blank, a value will be generated for you.
+
+The `Select` component renders all the necessary wrapping and associated text
+elements, but the select options _need_ to be child `<option>` HTML elements.
+
+```jsx
+<Select labelText="What is your favorite color?" name="color">
+  <option value="red">Red</option>
+  <option value="green">Green</option>
+  <option value="blue">Blue</option>
+  <option value="black">Black</option>
+  <option value="white">White</option>
+</Select>
+```
+
+<Canvas withToolbar>
   <Story
     name="Select"
     args={{
-      id: "mySelect",
+      helperText: "This is the helper text.",
+      invalidText: "This is the error text :(",
+      isDisabled: false,
+      isInvalid: false,
+      isRequired: false,
       labelText: "What is your favorite color?",
+      name: "color",
       showLabel: true,
-      helperText: "Choose wisely.",
-      errorText: "Waaaaaaaa!",
-      errored: false,
-      required: true,
-      disabled: false,
-      selectedOption: "Green",
-      attributes: {
-        onFocus: action("focus"),
-        onBlur: action("blur"),
-        onChange: action("onChange"),
-      },
-    }}
-    argTypes={{
-      ariaLabel: { table: { disable: true } },
-      helperTextId: { table: { disable: true } },
-      isRequired: { table: { disable: true } },
-      labelId: { table: { disable: true } },
+      showOptReqLabel: true,
     }}
   >
     {(args) => (
       <Select {...args}>
-        <option aria-selected={true}></option>
-        <option aria-selected={false}>Red</option>
-        <option aria-selected={false}>Green</option>
-        <option aria-selected={false}>Blue</option>
-        <option aria-selected={false}>Black</option>
-        <option aria-selected={false}>White</option>
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
       </Select>
     )}
   </Story>
-</Preview>
+</Canvas>
 
 <ArgsTable story="Select" />
 
-### Deprecated Props
-
-The following props have been deprecated: `ariaLabel`, `helperTextId`, `isRequired` and `labelId`. They are still available to use, but they will be removed in a future release.
-
 ## Labelling Variations
 
-A Select can be rendered with or without visible labels. When `showLabel` is set to `false`, an `aria-label` attribute is added to the select input to maintain accessibility.
-
-<Preview>
-  <Story
-    name="Labelling Variations"
-    args={{
-      labelText: "What is your favorite color?",
-      showLabel: false,
-    }}
-  >
-    {(args) => (
-      <>
-        <Select {...args}>
-          <option aria-selected={true}></option>
-          <option aria-selected={false}>Red</option>
-          <option aria-selected={false}>Green</option>
-          <option aria-selected={false}>Blue</option>
-          <option aria-selected={false}>Black</option>
-          <option aria-selected={false}>White</option>
-        </Select>
-      </>
-    )}
-  </Story>
-</Preview>
+A Select can be rendered with or without a visible label. When `showLabel` is
+set to `false`, an `aria-label` attribute is added to the select input to
+maintain accessibility. If the component needs to be required, the
+`showOptReqLabel` prop can be used to show or hide the "Required"/"Optional"
+text within the `label` element.
 
 <Canvas>
-  <Select labelText="What is your favorite color?" showLabel={true}>
-    <option aria-selected={true}></option>
-    <option aria-selected={false}>Red</option>
-    <option aria-selected={false}>Green</option>
-    <option aria-selected={false}>Blue</option>
-    <option aria-selected={false}>Black</option>
-    <option aria-selected={false}>White</option>
-  </Select>
+  <Story name="Labelling Variations">
+    <VStack align="stretch" spacing={8}>
+      <Select
+        labelText="What is your favorite color?"
+        helperText="Display the label"
+        name="color"
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        labelText="What is your favorite color?"
+        helperText="Do not display the label"
+        name="color"
+        showLabel={false}
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        labelText="What is your favorite color?"
+        helperText="Display the Required/Optional text"
+        name="color"
+        isRequired
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+      <Select
+        labelText="What is your favorite color?"
+        helperText="Do not display the Required/Optional text"
+        name="color"
+        showOptReqLabel={false}
+        isRequired
+      >
+        <option value="red">Red</option>
+        <option value="green">Green</option>
+        <option value="blue">Blue</option>
+        <option value="black">Black</option>
+        <option value="white">White</option>
+      </Select>
+    </VStack>
+  </Story>
 </Canvas>
 
-<Canvas>
-  <Select
-    labelText="What is your favorite color?"
-    showLabel={false}
-    helperText="Choose wisely!"
-  >
-    <option aria-selected={true}></option>
-    <option aria-selected={false}>Red</option>
-    <option aria-selected={false}>Green</option>
-    <option aria-selected={false}>Blue</option>
-    <option aria-selected={false}>Black</option>
-    <option aria-selected={false}>White</option>
-  </Select>
-</Canvas>
+## Errored
 
 <Canvas>
-  <Select
-    labelText="What is your favorite color?"
-    showLabel={true}
-    helperText="Choose wisely!"
-  >
-    <option aria-selected={true}></option>
-    <option aria-selected={false}>Red</option>
-    <option aria-selected={false}>Green</option>
-    <option aria-selected={false}>Blue</option>
-    <option aria-selected={false}>Black</option>
-    <option aria-selected={false}>White</option>
-  </Select>
+  <DSProvider>
+    <Select
+      labelText="What is your favorite color?"
+      helperText="This is the helper text."
+      invalidText="This is the error text :("
+      name="color"
+      isInvalid
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  </DSProvider>
 </Canvas>
 
-<Canvas>
-  <Select
-    labelText="What is your favorite color?"
-    showLabel={false}
-    helperText="Choose wisely!"
-    errorText="Waaaaaa!"
-    errored={true}
-  >
-    <option aria-selected={true}></option>
-    <option aria-selected={false}>Red</option>
-    <option aria-selected={false}>Green</option>
-    <option aria-selected={false}>Blue</option>
-    <option aria-selected={false}>Black</option>
-    <option aria-selected={false}>White</option>
-  </Select>
-</Canvas>
+## Disabled
 
 <Canvas>
-  <Select
-    labelText="What is your favorite color?"
-    showLabel={true}
-    helperText="Choose wisely!"
-    errorText="Waaaaaa!"
-    errored={true}
-  >
-    <option aria-selected={true}></option>
-    <option aria-selected={false}>Red</option>
-    <option aria-selected={false}>Green</option>
-    <option aria-selected={false}>Blue</option>
-    <option aria-selected={false}>Black</option>
-    <option aria-selected={false}>White</option>
-  </Select>
+  <DSProvider>
+    <Select
+      labelText="What is your favorite color?"
+      helperText="This is the helper text."
+      invalidText="This is the error text :("
+      name="color"
+      isDisabled
+    >
+      <option value="red">Red</option>
+      <option value="green">Green</option>
+      <option value="blue">Blue</option>
+      <option value="black">Black</option>
+      <option value="white">White</option>
+    </Select>
+  </DSProvider>
 </Canvas>
 
-## Deprecated Implementation
-
-The `ariaLabel`, `helperTextId`, `isRequired` and `labelId` have been deprecated, but they are still available to use until they are removed in a future release. The code below uses all four deprecated props in conjunction with the `Label` and `HelperErrorText` components to render a fully functional and accessible select input.
-
-<Preview withToolbar>
-  <Story
-    name="Deprecated Implementation"
-    args={{
-      labelText: "What is your favorite color?",
-      showLabel: false,
-    }}
-  >
-    {(args) => (
-      <>
-        <Label htmlFor="select" optReqFlag="Required" id={"label"}>
-          Fruit on your island
-        </Label>
-        <Select
-          name="optionalLabelSelect"
-          id={"select"}
-          isRequired={false}
-          ariaLabel="Select Label"
-          labelId={"label"}
-          helperTextId={"helperText"}
-          selectedOption="Option Three"
-        >
-          <option aria-selected={true}>Option One</option>
-          <option aria-selected={false}>Option Two</option>
-          <option aria-selected={false}>Option Three</option>
-          <option aria-selected={false}>Option Four</option>
-          <option aria-selected={false}>Option Five</option>
-        </Select>
-        <HelperErrorText isError={false} id={"helperText"}>
-          Once you pick a fruit for your island it cannot be changed, so choose
-          wisely!
-        </HelperErrorText>
-      </>
-    )}
-  </Story>
-</Preview>
+## Getting Select Data Value
+
+### Controlled Component using `value` and `onChange` props
+
+If your application uses controlled React components and the DS `Select`
+component must be controlled, you can control and extract the data through the
+`value` and `onChange` props. This will be called every time a new `option`
+value is selected.
+
+```jsx
+const value = "red";
+const onChange = (e) => {
+  // This will return the value selected through the event object.
+  console.log(e.target.value);
+};
+// ...
+
+<Select
+  labelText="What is your favorite color?"
+  helperText="This is the helper text."
+  name="color"
+  value={value}
+  onChange={onChange}
+>
+  <option value="red">Red</option>
+  <option value="green">Green</option>
+  <option value="blue">Blue</option>
+  <option value="black">Black</option>
+  <option value="white">White</option>
+</Select>;
+```
+
+### Uncontrolled Component using `ref`s
+
+If your application uses uncontrolled components, you can pass a React `ref`
+prop to the DS Select component to get the selected value from the DOM.
+
+```jsx
+const selectRef = React.createRef<HTMLSelectElement>();
+// ...
+<Select
+  labelText="What is your favorite color?"
+  helperText="This is the helper text."
+  name="color"
+>
+  <option value="red">Red</option>
+  <option value="green">Green</option>
+  <option value="blue">Blue</option>
+  <option value="black">Black</option>
+  <option value="white">White</option>
+</Select>
+
+// ...
+// Get the value through:
+const onSubmit = () => {
+  // ...
+  const selectValue = selectRef.current.value;
+};
+```