@simplybusiness/mobius 3.0.0

package/src/components/Select/Select.story.mdx

@@ -0,0 +1,362 @@
+import { Meta, ArgsTable, Story } from "@storybook/addon-docs";
+import { Select } from "./Select";
+import { useState } from "react";
+import { Option } from "../Option";
+import { Box } from "../Box";
+import { excludeControls } from "../../utils/excludeControls";
+
+<Meta
+  title="Forms/Select"
+  component={Select}
+  argTypes={{
+    validationState: {
+      control: {
+        type: "radio",
+        options: {
+          valid: "valid",
+          invalid: "invalid",
+          neither: "",
+        },
+        defaultValue: {
+          neither: "",
+        },
+      },
+    },
+    value: {
+      control: "select",
+      options: ["", "red", "blue", "green"],
+    },
+    defaultValue: {
+      control: "select",
+      options: ["", "red", "blue", "green"],
+    },
+    ...excludeControls("className", "onChange", "defaultValue"),
+  }}
+/>
+
+# Select
+
+Select allows to pick a single option from a list.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Select, Option } from "@simplybusiness/mobius";
+```
+
+## Examples
+
+### Normal
+
+<Story
+  name="Normal"
+  args={{
+    name: "color",
+    label: "Colors",
+    defaultValue: "",
+    validationState: "",
+    errorMessage: "",
+    isDisabled: false,
+  }}
+>
+  {args => (
+    <Select {...args}>
+      <Option key="none" value="" isDisabled>
+        Please select a color
+      </Option>
+      <Option key="red" value="red">
+        Red
+      </Option>
+      <Option key="blue" value="blue">
+        Blue
+      </Option>
+      <Option key="green" value="green">
+        Green
+      </Option>
+    </Select>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Select, Option } from "@simplybusiness/mobius";
+
+<Select name="color" label="Colors" defaultValue="">
+  <Option key="none" value="" isDisabled>
+    Please select a color
+  </Option>
+  <Option key="red" value="red">
+    Red
+  </Option>
+  <Option key="blue" value="blue">
+    Blue
+  </Option>
+  <Option key="green" value="green">
+    Green
+  </Option>
+</Select>
+```
+
+### Controlled Value
+
+<Story
+  name="Controlled Value"
+  args={{
+    name: "color",
+    label: "Colors",
+    value: "green",
+    validationState: "",
+    errorMessage: "",
+    isDisabled: false,
+  }}
+>
+  {args => (
+    <Select {...args}>
+      <Option key="none" value="" isDisabled>
+        Please select a color
+      </Option>
+      <Option key="red" value="red">
+        Red
+      </Option>
+      <Option key="blue" value="blue">
+        Blue
+      </Option>
+      <Option key="green" value="green">
+        Green
+      </Option>
+    </Select>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Select, Option } from "@simplybusiness/mobius";
+
+<Select name="color" label="Colors" value="green">
+  <Option key="none" value="" isDisabled>
+    Please select a color
+  </Option>
+  <Option key="red" value="red">
+    Red
+  </Option>
+  <Option key="blue" value="blue">
+    Blue
+  </Option>
+  <Option key="green" value="green">
+    Green
+  </Option>
+</Select>
+```
+
+### Disabled
+
+<Story
+  name="Disabled"
+  args={{
+    name: "color",
+    label: "Colors",
+    defaultValue: "green",
+    validationState: "",
+    errorMessage: "",
+    isDisabled: true,
+  }}
+>
+  {args => (
+    <Select {...args}>
+      <Option key="none" value="" isDisabled>
+        Please select a color
+      </Option>
+      <Option key="red" value="red">
+        Red
+      </Option>
+      <Option key="blue" value="blue">
+        Blue
+      </Option>
+      <Option key="green" value="green">
+        Green
+      </Option>
+    </Select>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Select, Option } from "@simplybusiness/mobius";
+
+<Select name="color" label="Colors" defaultValue="green" isDisabled={true}>
+  <Option key="none" value="">
+    Please select a color
+  </Option>
+  <Option key="red" value="red">
+    Red
+  </Option>
+  <Option key="blue" value="blue">
+    Blue
+  </Option>
+  <Option key="green" value="green">
+    Green
+  </Option>
+</Select>
+```
+
+### Valid
+
+<Story
+  name="Valid"
+  args={{
+    name: "color",
+    label: "Colors",
+    defaultValue: "green",
+    validationState: "valid",
+    errorMessage: "",
+    isDisabled: false,
+  }}
+>
+  {args => (
+    <Select {...args}>
+      <Option key="none" value="" isDisabled>
+        Please select a color
+      </Option>
+      <Option key="red" value="red">
+        Red
+      </Option>
+      <Option key="blue" value="blue">
+        Blue
+      </Option>
+      <Option key="green" value="green">
+        Green
+      </Option>
+    </Select>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Select, Option } from "@simplybusiness/mobius";
+
+<Select
+  name="color"
+  label="Colors"
+  defaultValue="green"
+  validationState="valid"
+>
+  <Option key="none" value="" isDisabled>
+    Please select a color
+  </Option>
+  <Option key="red" value="red">
+    Red
+  </Option>
+  <Option key="blue" value="blue">
+    Blue
+  </Option>
+  <Option key="green" value="green">
+    Green
+  </Option>
+</Select>
+```
+
+### Invalid
+
+<Story
+  name="Invalid"
+  args={{
+    name: "color",
+    label: "Colors",
+    defaultValue: "green",
+    validationState: "invalid",
+    errorMessage: "Unacceptable color",
+    isDisabled: false,
+  }}
+>
+  {args => (
+    <Select {...args}>
+      <Option key="none" value="" isDisabled>
+        Please select a color
+      </Option>
+      <Option key="red" value="red">
+        Red
+      </Option>
+      <Option key="blue" value="blue">
+        Blue
+      </Option>
+      <Option key="green" value="green">
+        Green
+      </Option>
+    </Select>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Select, Option } from "@simplybusiness/mobius";
+
+<Select
+  name="color"
+  label="Colors"
+  defaultValue="green"
+  validationState="invalid"
+  errorMessage="Unacceptable color"
+>
+  <Option key="none" value="" isDisabled>
+    Please select a color
+  </Option>
+  <Option key="red" value="red">
+    Red
+  </Option>
+  <Option key="blue" value="blue">
+    Blue
+  </Option>
+  <Option key="green" value="green">
+    Green
+  </Option>
+</Select>
+```
+
+## Accessibility
+
+When the `label` prop is not provided, make sure to provide the `aria-label` prop instead. If the select is labeled by a separate element, the `aria-labelledby` props must be used with the id of the labeling element.
+
+## Events
+
+The `onChange` prop can be used to listen to changes of the selected option state of the select. See the prop table for the complete list of events supported.
+
+## Props
+
+<ArgsTable of={Select} />
+
+## Component HTML Structure and Class names
+
+The following HTML is rendered for a Select:
+
+```html
+<div>
+  <label class="mobius/Label" for="{select-id}" id="{label-id}"> Color </label>
+  <div class="mobius/SelectWrapper">
+    <select class="mobius/Select" id="{select-id}" aria-labelledby="{label-id}">
+      <option>Red</option>
+      <option>Blue</option>
+    </select>
+    <span class="mobius/SelectIcon"></span>
+  </div>
+</div>
+```
+
+The span allows for an image overlay to replace the standard select UX in browsers. Class names are augmented with the following flags if true:
+
+- --is-focused
+- --is-disabled
+- --is-hovered
+- --is-selected
+- --is-valid
+- --is-invalid
+- --is-optional
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Select) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)

package/src/components/Select/Select.test.tsx

@@ -0,0 +1,205 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { matchers } from "@emotion/jest";
+import { Select } from ".";
+import { Option } from "..";
+
+const CLASS_NAME = "mobius/Select";
+const LABEL_CLASS_NAME = "mobius/Label";
+
+expect.extend(matchers);
+
+describe("Select", () => {
+  it("should render without error", () => {
+    const component = render(
+      <Select label="Color">
+        <Option>Red</Option>
+        <Option>Blue</Option>
+      </Select>,
+    );
+    expect(component).toBeTruthy();
+  });
+
+  it("should call onChange when clicked", async () => {
+    const callback = jest.fn();
+    const { getByLabelText } = render(
+      <Select label="Color" name="color" onChange={callback}>
+        <Option>Red</Option>
+        <Option>Blue</Option>
+      </Select>,
+    );
+    await userEvent.selectOptions(getByLabelText("Color"), ["Red"]);
+    expect(callback).toHaveBeenCalledWith("Red");
+  });
+
+  describe("with errors", () => {
+    it("should render the error", () => {
+      const { getByText } = render(
+        <Select label="Color" name="color" errorMessage="Required">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(getByText("Required")).toBeTruthy();
+    });
+
+    it("should set aria-invalid to true", () => {
+      const { getByLabelText } = render(
+        <Select label="Color" name="color" errorMessage="Required">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(getByLabelText("Color").getAttribute("aria-invalid")).toBeTruthy();
+    });
+
+    it("should set the correct aria-describedby attribute", () => {
+      const { getByLabelText } = render(
+        <Select label="Color" name="color" errorMessage="Required">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(getByLabelText("Color")).toHaveAccessibleDescription("Required");
+    });
+  });
+
+  describe("given a disabled option", () => {
+    it("should render with disabled attribute applied", () => {
+      render(
+        <Select label="Color" name="color">
+          <Option isDisabled>Please select a color</Option>
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+
+      const options = screen.queryAllByRole("option");
+
+      expect(options[0]).toBeDisabled();
+    });
+  });
+
+  describe("isRequired", () => {
+    it("should set aria-required to true", () => {
+      render(
+        <Select label="Color" name="color" errorMessage="Required" isRequired>
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByLabelText("Color")).toHaveAttribute(
+        "aria-required",
+        "true",
+      );
+    });
+
+    it("should have className of --is-required when true", () => {
+      render(
+        <Select label="Color" name="color" errorMessage="Required" isRequired>
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByLabelText("Color")).toHaveClass("--is-required");
+    });
+
+    it("should have className of --is-optional when false", () => {
+      render(
+        <Select
+          label="Color"
+          name="color"
+          errorMessage="Required"
+          isRequired={false}
+        >
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByLabelText("Color")).toHaveClass("--is-optional");
+    });
+
+    it("should have neither --is-required nor --is-optional when unset", () => {
+      render(
+        <Select label="Color" name="color" errorMessage="Required">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByLabelText("Color")).not.toHaveClass("--is-required");
+      expect(screen.getByLabelText("Color")).not.toHaveClass("--is-optional");
+    });
+  });
+
+  describe("uses correct class names", () => {
+    it("uses Mobius class", () => {
+      const { container } = render(
+        <Select label="Color" data-testid="test">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(container.firstChild).toHaveClass("mobius");
+    });
+
+    it("uses base Mobius class", () => {
+      render(
+        <Select label="Color" data-testid="test">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByTestId("test")).toHaveClass(CLASS_NAME);
+    });
+
+    it("includes custom class name", () => {
+      render(
+        <Select label="Color" data-testid="test" className="my-class">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(screen.getByTestId("test")).toHaveClass("my-class");
+      expect(screen.getByTestId("test")).toHaveClass(CLASS_NAME);
+    });
+
+    it("includes label class name", () => {
+      render(
+        <Select label="Color" data-testid="test">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      expect(
+        screen.getByTestId("test").closest("div")?.parentNode?.firstChild,
+      ).toHaveClass(LABEL_CLASS_NAME);
+    });
+
+    it("includes disabled class name", () => {
+      render(
+        <Select label="Color" data-testid="test" isDisabled>
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      const select = screen.getByTestId("test");
+      const selectIcon = select.nextElementSibling;
+      expect(select).toHaveClass("--is-disabled");
+      expect(selectIcon).toHaveClass("--is-disabled");
+    });
+
+    it("includes valid state class name", () => {
+      render(
+        <Select label="Color" data-testid="test" validationState="valid">
+          <Option>Red</Option>
+          <Option>Blue</Option>
+        </Select>,
+      );
+      const select = screen.getByTestId("test");
+      const selectIcon = select.nextElementSibling;
+      expect(select).toHaveClass("--is-valid");
+      expect(selectIcon).toHaveClass("--is-valid");
+    });
+  });
+});

package/src/components/Select/Select.tsx

@@ -0,0 +1,132 @@
+import {
+  forwardRef,
+  ReactElement,
+  Ref,
+  SyntheticEvent,
+  RefAttributes,
+} from "react";
+import { useLabel } from "@react-aria/label";
+import { DOMProps, LabelableProps, Validation } from "@react-types/shared";
+import clsx from "clsx";
+import { useFocusRing } from "@react-aria/focus";
+import { HoverProps, useHover } from "@react-aria/interactions";
+import { useSlotId } from "@react-aria/utils";
+import { ForwardedRefComponent } from "../../types/components";
+import { Flex } from "../Flex";
+import { ErrorMessage } from "../ErrorMessage";
+import { Label } from "../Label";
+import { OptionProps } from "../Option";
+import { spaceDelimitedList } from "../../utils/spaceDelimitedList";
+
+export type SelectElementType = HTMLSelectElement;
+export interface SelectProps
+  extends HoverProps,
+    LabelableProps,
+    Validation,
+    DOMProps,
+    RefAttributes<SelectElementType> {
+  name?: string;
+  onChange?: (value: string) => void;
+  value?: string;
+  defaultValue?: string;
+  className?: string;
+  errorMessage?: string;
+  children?: ReactElement<OptionProps>[] | ReactElement<OptionProps>;
+}
+
+export type SelectRef = Ref<SelectElementType>;
+
+const Select: ForwardedRefComponent<SelectProps, SelectElementType> =
+  forwardRef((props: SelectProps, ref: SelectRef) => {
+    const {
+      label,
+      onChange,
+      validationState,
+      errorMessage,
+      isDisabled = false,
+      isRequired,
+      ...otherProps
+    } = props;
+
+    const { labelProps, fieldProps } = useLabel({
+      label,
+      ...otherProps,
+    });
+    // focusProps are returned as type HTMLAttributes<HTMLElement> and not a synthetic event
+    const { isFocusVisible, focusProps } = useFocusRing({
+      within: true,
+    });
+    const { isHovered, hoverProps } = useHover({
+      ...otherProps,
+      isDisabled,
+    });
+
+    const stateClasses = {
+      "--is-focused": isFocusVisible,
+      "--is-disabled": isDisabled,
+      "--is-hovered": isHovered && !isDisabled,
+      "--is-valid": validationState === "valid",
+      "--is-invalid": validationState === "invalid",
+      "--is-required": typeof isRequired === "boolean" && isRequired,
+      "--is-optional": typeof isRequired === "boolean" && !isRequired,
+    };
+
+    const wrapperClasses = clsx(
+      "mobius/SelectWrapper",
+      stateClasses,
+      otherProps.className,
+    );
+    const selectClasses = clsx(
+      "mobius/Select",
+      stateClasses,
+      otherProps.className,
+    );
+    const labelClasses = clsx(
+      "mobius/Label",
+      stateClasses,
+      otherProps.className,
+    );
+    const iconClasses = clsx("mobius/SelectIcon", stateClasses);
+    const errorMessageId = useSlotId([Boolean(errorMessage), validationState]);
+    const describedBy = spaceDelimitedList([
+      errorMessageId,
+      props["aria-describedby"],
+    ]);
+
+    return (
+      <Flex
+        className="mobius mobius/SelectOuter"
+        css={{ flexDirection: "column" }}
+      >
+        {label && (
+          <Label {...labelProps} className={labelClasses}>
+            {label}
+          </Label>
+        )}
+        <div className={wrapperClasses} {...hoverProps} {...focusProps}>
+          <select
+            {...otherProps}
+            {...fieldProps}
+            {...focusProps}
+            ref={ref}
+            multiple={false}
+            className={selectClasses}
+            disabled={isDisabled}
+            aria-invalid={!!errorMessage}
+            aria-describedby={describedBy}
+            aria-required={isRequired}
+            onChange={(e: SyntheticEvent<HTMLSelectElement>) => {
+              if (onChange) {
+                onChange(e.currentTarget.value);
+              }
+            }}
+          />
+          <span className={iconClasses} />
+        </div>
+        <ErrorMessage id={errorMessageId} errorMessage={errorMessage} />
+      </Flex>
+    );
+  });
+
+Select.displayName = "Select";
+export { Select };

package/src/components/Select/index.tsx

@@ -0,0 +1 @@
+export * from "./Select";