@simplybusiness/mobius 3.0.0

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

@@ -0,0 +1,309 @@
+import { useState } from "react";
+import { Meta, ArgsTable, Canvas, Story } from "@storybook/addon-docs";
+import { ThemeContext } from "../../../contexts";
+import { Question } from "./Question";
+import { Box } from "../../Box";
+import { TextField } from "../../TextField";
+import { excludeControls } from "../../../utils/excludeControls";
+
+<Meta
+  title="Chopin/Question"
+  component={Question}
+  argTypes={{
+    validationState: {
+      control: {
+        type: "radio",
+        options: {
+          valid: "valid",
+          invalid: "invalid",
+          neither: "",
+        },
+        defaultValue: {
+          neither: "",
+        },
+      },
+    },
+    label: {
+      control: "text",
+    },
+    help: {
+      control: "text",
+    },
+    ...excludeControls("children", "className"),
+  }}
+  decorators={[
+    Story => (
+      <ThemeContext.Provider
+        value={{
+          breakpoints: [
+            { size: "xs", value: 320 },
+            { size: "sm", value: 480 },
+            { size: "md", value: 670 },
+            { size: "lg", value: 960 },
+            { size: "xl", value: 1200 },
+            { size: "xxl", value: 1320 },
+          ],
+        }}
+      >
+        <Story />
+      </ThemeContext.Provider>
+    ),
+  ]}
+  args={{
+    description: "",
+    errorMessage: "",
+    help: "",
+  }}
+/>
+
+# Question
+
+Question displays a questionnaire question.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Chopin } from "@simplybusiness/mobius";
+```
+
+## Examples
+
+### Normal
+
+<Story
+  name="Normal"
+  args={{
+    label: "Question label",
+    children: <TextField />,
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.Question label="Question label">
+  <TextField />
+</Chopin.Question>
+```
+
+<Story
+  name="With Description"
+  args={{
+    label: "Question label",
+    description:
+      "lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua",
+    children: <TextField />,
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+<Story
+  name="With Rich Description"
+  args={{
+    label: "Question label",
+    description: (
+      <ul>
+        <li>Item One</li>
+        <li>Item Two</li>
+      </ul>
+    ),
+    children: <TextField />,
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.Question
+  description="lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
+  label="Question label"
+
+>
+  <TextField />
+</Chopin.Question>
+```
+
+<Story
+  name="With Help text"
+  args={{
+    label: "Question label",
+    help: (
+      <>
+        <p>
+          This is a sample help text to demonstrate what help blocks look like
+          in questions.
+        </p>
+        <p>
+          This is a second paragraph to show that help texts aren't limited to
+          simple strings.
+        </p>
+      </>
+    ),
+    children: <TextField />,
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.Question
+  help={
+    <>
+      <p>
+        This is a sample help text to demonstrate what help blocks look like in
+        questions.
+      </p>
+      <p>
+        This is a second paragraph to show that help texts aren't limited to
+        simple strings.
+      </p>
+    </>
+  }
+  label="Question label"
+>
+  <TextField />
+</Chopin.Question>
+```
+
+<Story
+  name="With Error"
+  args={{
+    label: "Question label",
+    children: <TextField />,
+    errorMessage: "This field is required",
+    validationState: "invalid",
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.Question
+  errorMessage="This field is required"
+  label="Question label"
+  validationState="invalid"
+>
+  <TextField />
+</Chopin.Question>;
+```
+
+<Story
+  name="Complete Example"
+  args={{
+    label: "Question label",
+    description:
+      "lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua",
+    children: <TextField />,
+    help: (
+      <>
+        <p>
+          This is a sample help text to demonstrate what help blocks look like
+          in questions.
+        </p>
+        <p>
+          This is a second paragraph to show that help texts aren't limited to
+          simple strings.
+        </p>
+      </>
+    ),
+    errorMessage: "This field is required",
+    validationState: "invalid",
+  }}
+>
+  {args => <Question {...args} />}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Chopin } from "@simplybusiness/mobius";
+
+<Chopin.Question
+  description="lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
+  errorMessage="This field is required"
+  help={
+    <>
+      <p>
+        This is a sample help text to demonstrate what help blocks look like in
+        questions.
+      </p>
+      <p>
+        This is a second paragraph to show that help texts aren't limited to
+        simple strings.
+      </p>
+    </>
+  }
+  label="Question label"
+
+  validationState="invalid"
+>
+  <TextField />
+</Chopin.Question>
+```
+
+## Props
+
+<ArgsTable of={Question} />
+
+## Component HTML Structure and Class names
+
+```html
+<div class="chopin/Question">
+  <label class="mobius mobius/Label chopin/QuestionLabel">Question label</label>
+  <div class="chopin/QuestionHelp --is-closed">
+    <button class="chopin/QuestionHelpTrigger">
+      <span>Open Help</span>
+    </button>
+    <div class="chopin/QuestionHelpContent" role="tooltip">
+      <p>
+        This is sample help text to demonstrate what help blocks look like in
+        questions.
+      </p>
+    </div>
+  </div>
+  <p class="mobius mobius/Text p chopin/QuestionDescription">
+    This is a description for the question.
+  </p>
+  <div class="mobius mobius/Flex mobius/TextField --is-invalid">
+    <input class="mobius mobius/TextInput --is-invalid mobius/TextFieldInput" />
+    <div class="mobius mobius/ErrorMessage">
+      <span class="mobius/ErrorIcon"></span>
+      <span class="mobius mobius/Text mobius/ErrorText"
+        >This field is required</span
+      >
+    </div>
+  </div>
+</div>
+```
+
+Class names are augmented with the following flags if true:
+
+- --is-focused
+- --is-disabled
+- --is-hovered
+- --is-selected
+- --is-valid
+- --is-invalid
+- --has-help-open
+- --is-desktop
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Chopin/Question) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)

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

@@ -0,0 +1,161 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { matchers } from "@emotion/jest";
+import { Question } from ".";
+import { TextField } from "../../TextField";
+
+const WRAPPER_CLASS_NAME = "chopin/Question";
+
+expect.extend(matchers);
+
+describe("Question", () => {
+  it("should render without error", () => {
+    const component = render(
+      <Question label="Question">
+        <TextField />
+      </Question>,
+    );
+    expect(component).toBeTruthy();
+  });
+
+  it("should include accessible description", () => {
+    render(
+      <Question label="Question" description="Sample description">
+        <TextField />
+      </Question>,
+    );
+    expect(screen.getByLabelText("Question")).toHaveAccessibleDescription(
+      "Sample description",
+    );
+  });
+
+  it("should include `id` that matches `for` attribute in `<label>`", () => {
+    render(
+      <Question label="Question" description="Sample description">
+        <TextField />
+      </Question>,
+    );
+
+    const label = screen.getByLabelText("Question");
+    const input = screen.getByRole("textbox");
+
+    expect(label.id).toEqual(input.id);
+  });
+
+  it("should include accessible description with error", () => {
+    render(
+      <Question
+        label="Question"
+        description="Sample description"
+        errorMessage="Sample error"
+      >
+        <TextField />
+      </Question>,
+    );
+    expect(screen.getByLabelText("Question")).toHaveAccessibleDescription(
+      "Sample error Sample description",
+    );
+  });
+
+  describe("uses correct Question class name", () => {
+    it("uses chopin class", () => {
+      const { container } = render(
+        <Question label="Question">
+          <TextField />
+        </Question>,
+      );
+      expect(container.firstChild).toHaveClass(WRAPPER_CLASS_NAME);
+    });
+
+    it("includes valid class name", () => {
+      render(
+        <Question label="Question" validationState="valid">
+          <TextField />
+        </Question>,
+      );
+      expect(screen.getByLabelText("Question")).toHaveClass("--is-valid");
+    });
+
+    it("includes invalid class name", () => {
+      render(
+        <Question
+          label="Question"
+          validationState="invalid"
+          errorMessage="There is a problem"
+        >
+          <TextField />
+        </Question>,
+      );
+      expect(screen.getByLabelText("Question")).toHaveClass("--is-invalid");
+    });
+
+    it("includes custom class name", () => {
+      const { container } = render(
+        <Question
+          label="Question"
+          validationState="invalid"
+          errorMessage="There is a problem"
+          className="custom-class"
+        >
+          <TextField />
+        </Question>,
+      );
+
+      expect(container.firstChild).toHaveClass("custom-class");
+    });
+
+    it("includes open help class name when toggled", () => {
+      const { container } = render(
+        <Question label="Question" help="Help text">
+          <TextField />
+        </Question>,
+      );
+
+      const helpToggle = screen.getByRole("button");
+
+      fireEvent.click(helpToggle);
+
+      expect(container.firstChild).toHaveClass("--has-help-open");
+    });
+  });
+
+  describe("Help", () => {
+    it("should be mouse accessible", async () => {
+      render(
+        <Question label="Question" help="This is a help message">
+          <TextField />
+        </Question>,
+      );
+      await userEvent.click(screen.getByRole("button", { name: "Open Help" }));
+      expect(screen.queryByRole("tooltip")).toBeInTheDocument();
+      await userEvent.click(screen.getByRole("button", { name: "Close Help" }));
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+
+    it("should be keyboard accessible", async () => {
+      render(
+        <Question label="Question" help="This is a help message">
+          <TextField />
+        </Question>,
+      );
+      await userEvent.tab();
+      await userEvent.keyboard("{enter}");
+      expect(screen.queryByRole("tooltip")).toBeInTheDocument();
+      await userEvent.keyboard("{enter}");
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+
+    it("should close on escape key", async () => {
+      render(
+        <Question label="Question" help="This is a help message">
+          <TextField />
+        </Question>,
+      );
+      await userEvent.tab();
+      await userEvent.keyboard("{enter}");
+      expect(screen.queryByRole("tooltip")).toBeInTheDocument();
+      await userEvent.keyboard("{escape}");
+      expect(screen.queryByRole("tooltip")).not.toBeInTheDocument();
+    });
+  });
+});

package/src/components/Chopin/Question/Question.tsx

@@ -0,0 +1,95 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  ReactNode,
+  useState,
+  ReactElement,
+} from "react";
+import clsx from "clsx";
+import { useId } from "@react-aria/utils";
+import { useBreakpoint } from "../../../hooks";
+import { Label } from "../../Label";
+import { Text } from "../../Text";
+import { QuestionHelp } from "../QuestionHelp/QuestionHelp";
+
+export interface QuestionProps {
+  label?: ReactElement | string;
+  description?: string | ReactNode;
+  errorMessage?: string;
+  children?: ReactNode;
+  validationState?: "valid" | "invalid" | "";
+  help?: ReactNode;
+  className?: string;
+}
+
+export function Question({
+  label,
+  description,
+  children,
+  errorMessage,
+  validationState,
+  help,
+  className,
+}: QuestionProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const labelId = useId();
+  const descriptionId = useId();
+  const forAttr = useId();
+  const { up } = useBreakpoint();
+  const isDesktop = up("md");
+
+  const classes = clsx(
+    "chopin",
+    "chopin/Question",
+    {
+      "--has-help-open": isOpen,
+    },
+    isDesktop ? "--is-desktop" : "",
+    className,
+  );
+
+  const handleChange = (state: boolean) => {
+    setIsOpen(state);
+  };
+
+  // Allow for rich html descriptions
+  const DescriptionComponent = isValidElement(description) ? "div" : Text;
+
+  const labelClasses = clsx("chopin/QuestionLabel", {
+    "--is-valid": validationState === "valid",
+    "--is-invalid": validationState === "invalid",
+  });
+
+  return (
+    <div className={classes}>
+      <Label htmlFor={forAttr} id={labelId} className={labelClasses}>
+        {label}
+      </Label>
+      {help && (
+        <QuestionHelp onChange={handleChange} isDesktop={isDesktop}>
+          {help}
+        </QuestionHelp>
+      )}
+      {description && (
+        <DescriptionComponent
+          id={descriptionId}
+          className="chopin/QuestionDescription"
+        >
+          {description}
+        </DescriptionComponent>
+      )}
+      {Children.map(children, child =>
+        isValidElement(child)
+          ? cloneElement(child, {
+              errorMessage,
+              validationState,
+              id: forAttr,
+              "aria-labelledby": labelId,
+              "aria-describedby": description ? descriptionId : undefined,
+            } as any)
+          : child,
+      )}
+    </div>
+  );
+}

package/src/components/Chopin/Question/index.tsx

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