@simplybusiness/mobius 3.0.0

package/src/components/Checkbox/Checkbox.story.mdx

@@ -0,0 +1,208 @@
+import { useState } from "react";
+import { Meta, ArgsTable, Canvas, Story } from "@storybook/addon-docs";
+import { Checkbox } from "./Checkbox";
+import { Box } from "../Box";
+import { excludeControls } from "../../utils/excludeControls";
+
+<Meta
+  title="Forms/Checkbox"
+  component={Checkbox}
+  argTypes={{
+    validationState: {
+      control: {
+        type: "radio",
+        options: {
+          valid: "valid",
+          invalid: "invalid",
+          neither: "",
+        },
+        defaultValue: {
+          neither: "",
+        },
+      },
+    },
+    ...excludeControls("className"),
+  }}
+/>
+
+# Checkbox
+
+Checkbox allows a user to select one or more options from a list.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Checkbox } from "@simplybusiness/mobius";
+```
+
+## Examples
+
+### Normal
+
+<Canvas>
+  <Story
+    name="Normal"
+    args={{
+      label: "Value",
+      isDisabled: false,
+      isIndeterminate: false,
+      errorMessage: "",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+### Disabled
+
+<Canvas>
+  <Story
+    name="Disabled"
+    args={{
+      label: "Value",
+      isDisabled: true,
+      isIndeterminate: false,
+      errorMessage: "",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+### Indeterminate
+
+<Canvas>
+  <Story
+    name="Indeterminate"
+    args={{
+      label: "Value",
+      isDisabled: false,
+      isIndeterminate: true,
+      errorMessage: "",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+### Valid
+
+<Canvas>
+  <Story
+    name="Valid"
+    args={{
+      label: "Value",
+      isDisabled: false,
+      isIndeterminate: false,
+      errorMessage: "",
+      validationState: "valid",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+### Invalid
+
+<Canvas>
+  <Story
+    name="Invalid"
+    args={{
+      label: "Value",
+      isDisabled: false,
+      isIndeterminate: false,
+      validationState: "invalid",
+      errorMessage: "This is an error message",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+### Long label
+
+<Canvas>
+  <Story
+    name="Long label"
+    args={{
+      label: (
+        <>
+          Example
+          <br />
+          of
+          <br />
+          long
+          <br />
+          label
+          <br />
+          text
+          <br />
+        </>
+      ),
+      isDisabled: false,
+      isIndeterminate: false,
+      validationState: "",
+      errorMessage: "",
+      defaultSelected: false,
+    }}
+  >
+    {args => <Checkbox {...args} />}
+  </Story>
+</Canvas>
+
+## Accessibility
+
+When the `label` prop is not provided, make sure to provide the `aria-label` prop instead. If the checkbox 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 state of the checkbox. See the prop table for the complete list of events supported.
+
+## Props
+
+<ArgsTable of={Checkbox} />
+
+## Component HTML Structure and Class names
+
+The following example HTML is rendered for a Checkbox:
+
+```html
+<div>
+  <label class="mobius/Checkbox --is-invalid" label="Checkbox">
+    <input class="mobius/CheckboxInput --is-invalid" />
+    <div class="mobius/CheckboxIcon --is-invalid"></div>
+    <span class="mobius/CheckboxLabel">Checkbox</span>
+  </label>
+  <div class="mobius/ErrorMessage">
+    <span class="mobius/ErrorIcon"></span>
+    <span class="mobius/Text span mobius/ErrorText"> There is a problem </span>
+  </div>
+</div>
+```
+
+Class names are augmented with the following flags if true:
+
+- --is-focused
+- --is-disabled
+- --is-indeterminate
+- --is-hovered
+- --is-selected
+- --is-valid
+- --is-invalid
+- --is-required
+- --is-optional
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Checkbox) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)

package/src/components/Checkbox/Checkbox.test.tsx

@@ -0,0 +1,205 @@
+import React, { Fragment } from "react";
+import { render, fireEvent, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { matchers } from "@emotion/jest";
+import { Checkbox, CheckboxGroup } from ".";
+
+const WRAPPER_CLASS_NAME = "mobius/Checkbox";
+const INPUT_CLASS_NAME = "mobius/CheckboxInput";
+
+expect.extend(matchers);
+
+describe.each([
+  ["Grouped checkbox", CheckboxGroup, { label: "Checkbox Group" }],
+  ["Ungrouped checkbox", Fragment, {}],
+])("%s", (_description, Container, containerProps) => {
+  it("should render without error", () => {
+    const component = render(
+      <Container {...containerProps}>
+        <Checkbox label="Checkbox" value="value" />
+      </Container>,
+    );
+    expect(component).toBeTruthy();
+  });
+
+  it("should call onChange when clicked", () => {
+    const callback = jest.fn();
+    const component = render(
+      <Container {...containerProps}>
+        <Checkbox label="Checkbox" onChange={callback} value="value" />
+      </Container>,
+    );
+    fireEvent.click(component.container.querySelector("input")!);
+    expect(callback).toHaveBeenCalledWith(true);
+  });
+
+  it("should be selectable via keyboard", async () => {
+    const callback = jest.fn();
+    render(
+      <Container {...containerProps}>
+        <Checkbox label="Checkbox" onChange={callback} value="value" />
+      </Container>,
+    );
+    await userEvent.tab();
+    await userEvent.keyboard("[Space]");
+    expect(callback).toHaveBeenCalledWith(true);
+
+    await userEvent.keyboard("[Space]");
+    expect(callback).toHaveBeenCalledWith(false);
+  });
+
+  it("should set the correct aria-describedby attribute", () => {
+    const { getByLabelText } = render(
+      <Checkbox label="I agree" name="agree" errorMessage="Required" />,
+    );
+    expect(getByLabelText("I agree")).toHaveAccessibleDescription("Required");
+  });
+
+  it('should set aria-checked="mixed" for indeterminate state', () => {
+    const { getByLabelText } = render(
+      <Checkbox label="I agree" name="agree" isIndeterminate />,
+    );
+    expect(getByLabelText("I agree")).toHaveAttribute("aria-checked", "mixed");
+  });
+
+  describe("isRequired", () => {
+    it("should set aria-required to true", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" isRequired />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveAttribute(
+        "aria-required",
+        "true",
+      );
+    });
+
+    it("should have className of --is-required when true", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" isRequired />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-required");
+    });
+
+    it("should have className of --is-optional when false", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" isRequired={false} />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-optional");
+    });
+
+    it("should have neither --is-required nor --is-optional when unset", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).not.toHaveClass(
+        "--is-required",
+      );
+      expect(screen.getByLabelText("Checkbox")).not.toHaveClass(
+        "--is-optional",
+      );
+    });
+  });
+
+  describe("uses correct class names", () => {
+    it("uses mobius Mobius class", () => {
+      const { container } = render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" />
+        </Container>,
+      );
+      expect(container.firstChild).toHaveClass("mobius");
+    });
+
+    it("uses base Mobius class", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass(INPUT_CLASS_NAME);
+    });
+
+    it("includes disabled class name", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" isDisabled value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-disabled");
+    });
+
+    it("includes valid class name", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" validationState="valid" value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-valid");
+    });
+
+    it("includes invalid class name", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox
+            label="Checkbox"
+            validationState="invalid"
+            errorMessage="There is a problem"
+            value="value"
+          />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-invalid");
+    });
+
+    it("includes custom class name", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" className="my-class" value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("my-class");
+      expect(screen.getByLabelText("Checkbox")).toHaveClass(INPUT_CLASS_NAME);
+    });
+
+    it("only sets id on the input element", () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox id="test" label="Checkbox" value="value" />
+        </Container>,
+      );
+      expect(screen.getByLabelText("Checkbox").getAttribute("id")).toEqual(
+        "test",
+      );
+    });
+
+    it("includes focused and selected class names", async () => {
+      render(
+        <Container {...containerProps}>
+          <Checkbox label="Checkbox" value="value" />
+        </Container>,
+      );
+
+      await userEvent.tab();
+      expect(screen.getByRole("checkbox")).toHaveClass("--is-focused");
+      expect(screen.getByRole("checkbox")).toHaveClass(INPUT_CLASS_NAME);
+      expect(screen.getByLabelText("Checkbox")).toHaveClass("--is-focused");
+      expect(screen.getByLabelText("Checkbox").closest("label")).toHaveClass(
+        WRAPPER_CLASS_NAME,
+      );
+
+      await userEvent.keyboard("[Space]");
+      expect(screen.getByRole("checkbox")).toHaveClass("--is-selected");
+
+      await userEvent.tab();
+      expect(screen.getByRole("checkbox")).not.toHaveClass("--is-hovered");
+    });
+  });
+});

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,21 @@
+import { forwardRef } from "react";
+import { ForwardedRefComponent } from "../../types/components";
+import { CheckboxElementType, CheckboxProps, CheckboxRef } from "./types";
+import { CheckboxGroupItem } from "./CheckboxGroupItem";
+import { useCheckboxContext } from "./CheckboxContext";
+import { CheckboxItem } from "./CheckboxItem";
+
+const Checkbox: ForwardedRefComponent<CheckboxProps, CheckboxElementType> =
+  forwardRef((props: CheckboxProps, ref: CheckboxRef) => {
+    const state = useCheckboxContext();
+    const isPartOfGroup = state != null;
+
+    if (isPartOfGroup) {
+      return <CheckboxGroupItem {...props} ref={ref} />;
+    }
+
+    return <CheckboxItem {...props} ref={ref} />;
+  });
+
+Checkbox.displayName = "Checkbox";
+export { Checkbox };

package/src/components/Checkbox/CheckboxContext.tsx

@@ -0,0 +1,13 @@
+import { CheckboxGroupState } from "@react-stately/checkbox";
+import { createContext, Context, useContext } from "react";
+
+export interface CheckboxGroupContext {
+  state: CheckboxGroupState;
+  isDisabled: boolean;
+  validationState?: "valid" | "invalid";
+}
+
+export const CheckboxContext: Context<CheckboxGroupContext | null> =
+  createContext<CheckboxGroupContext | null>(null);
+
+export const useCheckboxContext = () => useContext(CheckboxContext);

package/src/components/Checkbox/CheckboxGroup.story.mdx

@@ -0,0 +1,202 @@
+import { useState } from "react";
+import { Meta, ArgsTable, Canvas, Story } from "@storybook/addon-docs";
+import { CheckboxGroup, Checkbox } from ".";
+import { Box } from "../Box";
+import { excludeControls } from "../../utils/excludeControls";
+
+<Meta
+  title="Forms/CheckboxGroup"
+  component={CheckboxGroup}
+  argTypes={{
+    validationState: {
+      control: {
+        type: "radio",
+        options: {
+          valid: "valid",
+          invalid: "invalid",
+          neither: "",
+        },
+        defaultValue: {
+          neither: "",
+        },
+      },
+    },
+    ...excludeControls("className"),
+  }}
+/>
+
+# Checkbox
+
+CheckboxGroup allows a user to select one or more options from a list of checkboxes.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Checkbox } from "@simplybusiness/mobius";
+```
+
+## Examples
+
+### Normal
+
+<Canvas>
+  <Story
+    name="Normal"
+    args={{
+      label: "Value",
+      errorMessage: "",
+      isDisabled: false,
+      orientation: "vertical",
+    }}
+  >
+    {args => (
+      <CheckboxGroup {...args}>
+        <Checkbox label="Option 1" value="option1" />
+        <Checkbox label="Option 2" value="option2" />
+        <Checkbox label="Option 3" value="option3" />
+      </CheckboxGroup>
+    )}
+  </Story>
+</Canvas>
+
+### Disabled
+
+<Canvas>
+  <Story
+    name="Disabled"
+    args={{
+      label: "Value",
+      errorMessage: "",
+      isDisabled: true,
+      orientation: "vertical",
+    }}
+  >
+    {args => (
+      <CheckboxGroup {...args}>
+        <Checkbox label="Option 1" value="option1" />
+        <Checkbox label="Option 2" value="option2" />
+        <Checkbox label="Option 3" value="option3" />
+      </CheckboxGroup>
+    )}
+  </Story>
+</Canvas>
+
+### Valid
+
+<Canvas>
+  <Story
+    name="Valid"
+    args={{
+      label: "Value",
+      errorMessage: "",
+      isDisabled: false,
+      validationState: "valid",
+      orientation: "vertical",
+    }}
+  >
+    {args => (
+      <CheckboxGroup {...args}>
+        <Checkbox label="Option 1" value="option1" />
+        <Checkbox label="Option 2" value="option2" />
+        <Checkbox label="Option 3" value="option3" />
+      </CheckboxGroup>
+    )}
+  </Story>
+</Canvas>
+
+### Invalid
+
+<Canvas>
+  <Story
+    name="Invalid"
+    args={{
+      label: "Value",
+      errorMessage: "This field is required",
+      isDisabled: false,
+      validationState: "invalid",
+      orientation: "vertical",
+    }}
+  >
+    {args => (
+      <CheckboxGroup {...args}>
+        <Checkbox label="Option 1" value="option1" />
+        <Checkbox label="Option 2" value="option2" />
+        <Checkbox label="Option 3" value="option3" />
+      </CheckboxGroup>
+    )}
+  </Story>
+</Canvas>
+
+## Accessibility
+
+When the `label` prop is not provided, make sure to provide the `aria-label` prop instead. If the checkbox is labeled by a separate element, the `aria-labelledby` props must be used with the id of the labeling element. For example:
+
+```jsx
+<CheckboxGroup aria-label="Checkbox Group">
+  <Checkbox label="Option 1" value="option1" />
+  <Checkbox label="Option 2" value="option2" />
+  <Checkbox label="Option 3" value="option3" />
+</CheckboxGroup>
+```
+
+## Events
+
+The `onChange` prop can be used to listen to changes of the selected state of the checkbox. See the prop table for the complete list of events supported.
+
+## Props
+
+<ArgsTable of={CheckboxGroup} />
+
+## Component HTML Structure and Class names
+
+The following example HTML is rendered for a CheckboxGroup:
+
+```html
+<div
+  role="group"
+  id="react-aria123"
+  aria-labelledby="react-aria456"
+  class="mobius mobius/CheckboxGroup"
+>
+  <label id="react-aria456" class="mobius mobius/Label">Value</label>
+  <div class="mobius mobius/CheckboxWrapper">
+    <label class="mobius mobius/Checkbox">
+      <input
+        type="checkbox"
+        aria-checked="false"
+        class="mobius/CheckboxInput"
+        value="option1"
+      />
+      <div class="mobius/CheckboxIcon"></div>
+      <span class="mobius/CheckboxLabel">Option 1</span>
+    </label>
+    <label class="mobius mobius/Checkbox">
+      <input
+        type="checkbox"
+        aria-checked="false"
+        class="mobius/CheckboxInput"
+        value="option2"
+      />
+      <div class="mobius/CheckboxIcon"></div>
+      <span class="mobius/CheckboxLabel">Option 2</span>
+    </label>
+  </div>
+</div>
+```
+
+Class names are augmented with the following flags if true:
+
+- --is-horizontal
+- --is-vertical
+- --is-required
+- --is-optional
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Checkbox) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)