@simplybusiness/mobius 3.0.0

package/src/components/Chopin/TradeSelector/TradeSelector.story.mdx

@@ -0,0 +1,169 @@
+import { Meta, ArgsTable, Canvas, Story } from "@storybook/addon-docs";
+import { TradeSelector, TradeSelectorProps } from ".";
+import { excludeControls } from "../../../utils/excludeControls";
+
+<Meta
+  title="Chopin/TradeSelector"
+  component={TradeSelector}
+  argTypes={excludeControls(
+    "className",
+    "elementType",
+    "labels",
+    "urls",
+    "onTradeSelected",
+  )}
+/>
+
+# TradeSelector
+
+The `TradeSelector` component is used to surface the most appropriate trade given a search criteria
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Chopin } from "@simplybusiness/mobius";
+```
+
+## Normal
+
+<Story name="Normal" args={{ minInput: 3, apiRequestDebounceInMs: 250 }}>
+  {args => <TradeSelector {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.TradeSelector />
+```
+
+## Without label
+
+<Story
+  name="Without label"
+  args={{ minInput: 3, apiRequestDebounceInMs: 250, hideLabel: true }}
+>
+  {args => <TradeSelector {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.TradeSelector />
+```
+
+## Labels
+
+The component has a predefined list of labels:
+
+| Label         | Default value                                   | Description                                                        |
+| ------------- | ----------------------------------------------- | ------------------------------------------------------------------ |
+| `input`       | What is your specific trade/profession?         | Appears at the very top of the component and is used for `<label>` |
+| `description` | Start typing to choose from over 1,000 options. | Appears underneath the `<label>` and it is used to guide the user  |
+| `placeholder` | e.g. Cleaner, builder, consultant               | Appears as placeholder text for the input field                    |
+| `loading`     | Loading...                                      | The label displays whilst trades are being requested               |
+| `exact`       | Exact matches for your search                   | Displays as a title for search results that are an exact match     |
+| `suggested`   | Suggested matches for your search               | Displays as a title for all other search results                   |
+| `noResults`   | View all trades                                 | Displays when no search results are found                          |
+
+In order to overwrite any of these labels, provide `labels` prop an object where keys match label names.
+
+For example, to overwrite `loading` and `suggested` labels you will use:
+
+`<Chopin.TradeSelector labels={{ loading: "Getting the results", suggested: "Other results" }} />`
+
+All other labels that are not specified will remain unchanged (as specified in the table above)
+
+In order to hide `input` and `description` you can use `hideLabel` prop as follows:
+
+`<Chopin.TradeSelector hideLabel />`
+
+## Props
+
+<ArgsTable of={TradeSelector} />
+
+## Component HTML Structure and Class names
+
+The following HTML is rendered for a TradeSelector:
+
+### With user input
+
+```html
+<div class="mobius chopin/TradeSelector">
+  <label class="mobius mobius/Label chopin/TradeSelectorLabel">
+    What is your specific trade/profession?
+  </label>
+  <p class="mobius mobius/Text caption chopin/TradeSelectorDescription">
+    Start typing to choose from over 1,000 options.
+  </p>
+  <div class="chopin/ComboBoxInputContainer">
+    <input class="chopin/ComboBoxInput" />
+    <div class="chopin/Popover">
+      <ul class="chopin/ListBox">
+        <li class="chopin/ListBoxSection">
+          <span class="chopin/ListBoxSectionHeading">
+            Exact matches for your search
+          </span>
+          <ul class="chopin/ListBoxSectionList">
+            <li class="chopin/TradeSelectorOption">
+              <span class="chopin/TradeSelectorOptionContent">
+                <strong>Consultant - training</strong>
+              </span>
+            </li>
+          </ul>
+        </li>
+        <li class="chopin/ListBoxSection">
+          <span class="chopin/ListBoxSectionHeading">
+            Suggested matches for your search
+          </span>
+          <ul class="chopin/ListBoxSectionList">
+            <li class="chopin/TradeSelectorOption">
+              <span class="chopin/TradeSelectorOptionContent">
+                <strong>Training</strong>
+              </span>
+            </li>
+            ...other options...
+          </ul>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <div class="mobius mobius/ErrorMessage">
+    <span class="mobius/ErrorIcon"></span>
+    <span class="mobius mobius/Text span mobius/ErrorText">
+      The service is currently unavailable. Please try again later
+    </span>
+  </div>
+</div>
+```
+
+### With trade selected
+
+```html
+<div class="mobius chopin/TradeSelector">
+  <label class="mobius mobius/Label chopin/TradeSelectorLabel">
+    What is your specific trade/profession?
+  </label>
+  <p class="mobius mobius/Text p">
+    You have selected ‘<strong>Security - training only</strong>’ as your
+    trade/profession.
+    <button
+      class="mobius/Link chopin/TradeSelectorButton"
+      aria-label="Change your selected profession"
+    >
+      Change
+    </button>
+  </p>
+</div>
+```
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Chopin/TradeSelector) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)

package/src/components/Chopin/TradeSelector/TradeSelector.test.tsx

@@ -0,0 +1,413 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { TradeSelector, ERROR_MESSAGE_SERVICE_UNAVAIALBLE } from ".";
+import { useTradeSelector } from "./useTradeSelector";
+import { exactResults, suggestedResults } from "./mockApiResults";
+
+const mockUseTradeSelector = useTradeSelector as jest.MockedFunction<
+  typeof useTradeSelector
+>;
+
+jest.mock("./useTradeSelector");
+
+const mockedApiResults = [...exactResults, ...suggestedResults];
+
+const trade = {
+  value: "Builder",
+  vertical: "business",
+  supported_verticals: ["contractors_combined"],
+  label: "<strong>Builder</strong>",
+  type: "exact",
+  trade_detail: null,
+  trade_type: null,
+  blocked: false,
+};
+
+describe("TradeSelector", () => {
+  it("should render without errors", () => {
+    mockUseTradeSelector.mockReturnValue({
+      inputValue: "",
+      isLoading: false,
+      trades: [],
+      onInputChange: () => {},
+      onSelectionChange: () => {},
+      error: undefined,
+      selectedTrade: undefined,
+      hasUserChangedMind: false,
+      onUserChangedMind: () => {},
+    });
+
+    render(<TradeSelector />);
+
+    const label = screen.getByText("What is your specific trade/profession?");
+    const input = screen.getByRole("combobox");
+    const placeholderText = "e.g. Cleaner, builder, consultant";
+
+    expect(label).toBeInTheDocument();
+    expect(input).toHaveAttribute("placeholder", placeholderText);
+  });
+
+  describe("given elementType", () => {
+    it("is not applied as element attribute", () => {
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "",
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      const { container } = render(<TradeSelector elementType="ul" />);
+
+      expect(container.firstChild).not.toHaveAttribute("elementtype", "ul");
+    });
+  });
+
+  describe("given no results for user input (that meets minimum input requirements)", () => {
+    it("should display a link to view all trades", async () => {
+      const userInput = "qwa";
+
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: userInput,
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector />);
+
+      await userEvent.tab();
+
+      await userEvent.keyboard(userInput);
+
+      await userEvent.keyboard("[Alt][ArrowDown]");
+
+      const noResultsLink = screen.getByText("View all trades");
+
+      expect(noResultsLink).toBeInTheDocument();
+
+      expect(noResultsLink).toHaveAttribute(
+        "href",
+        "https://quote.simplybusiness.co.uk/trades?vertical=business",
+      );
+    });
+  });
+
+  describe("given a set of results", () => {
+    describe("containing both exact matches and suggested trades", () => {
+      it("should display the results under their respective titles", async () => {
+        const userInput = "swim";
+
+        mockUseTradeSelector.mockReturnValue({
+          inputValue: userInput,
+          isLoading: false,
+          trades: mockedApiResults,
+          onInputChange: () => {},
+          onSelectionChange: () => {},
+          error: undefined,
+          selectedTrade: undefined,
+          hasUserChangedMind: false,
+          onUserChangedMind: () => {},
+        });
+
+        render(<TradeSelector />);
+
+        await userEvent.tab();
+
+        await userEvent.keyboard(userInput);
+
+        await userEvent.keyboard("[Alt][ArrowDown]");
+
+        await waitFor(() => {
+          const exactTitle = screen.getByText("Exact matches for your search");
+          const suggestedTitle = screen.getByText(
+            "Suggested matches for your search",
+          );
+          const groups = screen.getAllByRole("group");
+          const exactResultExample = document.querySelector(
+            '[data-key="Swim Shop"]',
+          );
+          const suggestedResultExample = document.querySelector(
+            '[data-key="Teacher / tutor"]',
+          );
+          const EXPECTED_NUMBER_OF_GROUPS = 2;
+
+          expect(exactTitle).toBeInTheDocument();
+          expect(suggestedTitle).toBeInTheDocument();
+          expect(groups.length).toBe(EXPECTED_NUMBER_OF_GROUPS);
+          expect(exactResultExample).toBeInTheDocument();
+          expect(suggestedResultExample).toBeInTheDocument();
+        });
+      });
+    });
+
+    describe("containing only the exact matches", () => {
+      it("should display the results under the title for exact matches", async () => {
+        const userInput = "swim";
+
+        mockUseTradeSelector.mockReturnValue({
+          inputValue: userInput,
+          isLoading: false,
+          trades: exactResults,
+          onInputChange: () => {},
+          onSelectionChange: () => {},
+          error: undefined,
+          selectedTrade: undefined,
+          hasUserChangedMind: false,
+          onUserChangedMind: () => {},
+        });
+
+        render(<TradeSelector />);
+
+        await userEvent.tab();
+
+        await userEvent.keyboard(userInput);
+
+        await userEvent.keyboard("[Alt][ArrowDown]");
+
+        await waitFor(() => {
+          const exactTitle = screen.getByText("Exact matches for your search");
+          const suggestedTitle = screen.queryByText(
+            "Suggested matches for your search",
+          );
+          const groups = screen.getAllByRole("group");
+          const exactResultExample = document.querySelector(
+            '[data-key="Swim Shop"]',
+          );
+          const suggestedResultExample = document.querySelector(
+            '[data-key="Teacher / tutor"]',
+          );
+          const EXPECTED_NUMBER_OF_GROUPS = 1;
+
+          expect(exactTitle).toBeInTheDocument();
+          expect(suggestedTitle).not.toBeInTheDocument();
+          expect(groups.length).toBe(EXPECTED_NUMBER_OF_GROUPS);
+          expect(exactResultExample).toBeInTheDocument();
+          expect(suggestedResultExample).toBeNull();
+        });
+      });
+    });
+  });
+
+  describe("given the API is unavailable", () => {
+    it("should show the error message", async () => {
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "",
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: Error(ERROR_MESSAGE_SERVICE_UNAVAIALBLE),
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector />);
+
+      expect(
+        screen.getByText(ERROR_MESSAGE_SERVICE_UNAVAIALBLE),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe("as well as an error message", () => {
+    it("should not display the overlay component", async () => {
+      const userInput = "swim";
+
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: userInput,
+        isLoading: false,
+        trades: mockedApiResults,
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: Error(ERROR_MESSAGE_SERVICE_UNAVAIALBLE),
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector />);
+
+      await userEvent.tab();
+
+      await userEvent.keyboard(userInput);
+
+      await userEvent.keyboard("[Alt][ArrowDown]");
+
+      await waitFor(() => {
+        const errorMessage = screen.getByText(
+          ERROR_MESSAGE_SERVICE_UNAVAIALBLE,
+        );
+        const overlay = screen.queryByLabelText("Suggestions");
+
+        expect(errorMessage).toBeInTheDocument();
+        expect(overlay).not.toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("when the user reduces the input value to a single character", () => {
+    it("should not display the overlay component", async () => {
+      const userInput = "s";
+
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: userInput,
+        isLoading: false,
+        trades: mockedApiResults,
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector />);
+
+      await userEvent.tab();
+
+      await userEvent.keyboard(userInput);
+
+      await userEvent.keyboard("[Alt][ArrowDown]");
+
+      await waitFor(() => {
+        const overlay = screen.queryByLabelText("Suggestions");
+
+        expect(overlay).not.toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("given a user has selected a trade", () => {
+    it("should display the selected trade and hide the input field", async () => {
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "",
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: trade,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      const expectedTrade = "Builder";
+
+      render(<TradeSelector />);
+
+      const partialText = screen.getByText(/You have selected/);
+      const chosenTrade = screen.getByText(expectedTrade);
+      const changeButton = screen.getByLabelText(
+        "Change your selected profession",
+      );
+
+      expect(partialText).toBeInTheDocument();
+      expect(chosenTrade).toBeInTheDocument();
+      expect(changeButton).toBeInTheDocument();
+    });
+  });
+
+  describe("clicking Change", () => {
+    it("should display the input field with previously selected trade", async () => {
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "",
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: trade,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      const expectedTrade = "Builder";
+
+      render(<TradeSelector />);
+
+      const changeButton = screen.getByLabelText(
+        "Change your selected profession",
+      );
+
+      await userEvent.click(changeButton);
+
+      waitFor(() => {
+        const inputField = screen.getByRole("combobox");
+
+        expect(inputField).toHaveDisplayValue(expectedTrade);
+      });
+    });
+  });
+
+  describe("given a user has selected the wrong trade", () => {
+    it("they should be able to choose a different trade", async () => {
+      const onInputChangeMock = jest.fn();
+
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "Fitness instructor",
+        isLoading: false,
+        trades: [],
+        onInputChange: onInputChangeMock,
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: trade,
+        hasUserChangedMind: true,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector />);
+
+      const inputField = screen.getByRole("combobox");
+
+      const newTrade = "Swimmer";
+
+      await userEvent.type(inputField, newTrade);
+
+      expect(onInputChangeMock).toHaveBeenCalledTimes(newTrade.length);
+    });
+  });
+
+  describe("given hideLabel is set to true", () => {
+    it("hides the label and the description and renders aria-label instead", () => {
+      mockUseTradeSelector.mockReturnValue({
+        inputValue: "",
+        isLoading: false,
+        trades: [],
+        onInputChange: () => {},
+        onSelectionChange: () => {},
+        error: undefined,
+        selectedTrade: undefined,
+        hasUserChangedMind: false,
+        onUserChangedMind: () => {},
+      });
+
+      render(<TradeSelector hideLabel />);
+
+      const label = screen.queryByText(
+        "What is your specific trade/profession?",
+      );
+      const description = screen.queryByText(
+        "Start typing to choose from over 1,000 options.",
+      );
+      const input = screen.getByRole("combobox");
+
+      expect(label).not.toBeInTheDocument();
+      expect(description).not.toBeInTheDocument();
+      expect(input).toHaveAttribute(
+        "aria-label",
+        "What is your specific trade/profession?",
+      );
+    });
+  });
+});