@simplybusiness/mobius 4.0.0 → 4.1.0

package/src/components/Popover/Popover.mdx

@@ -0,0 +1,107 @@
+import { Meta, ArgTypes, Story, Canvas } from "@storybook/addon-docs";
+import * as PopoverStories from "./Popover.stories";
+import { Popover } from "./Popover";
+
+<Meta of={PopoverStories} />
+
+# Popover
+
+The `Popover` component is used to display popup tooltips with additional information for users. Children of the Popover become tooltip contents and `trigger` is a render prop for the element that will present the Popover when clicked.
+
+When presented, the Popover will align (vertically) with the trigger element. By default it will appear below.
+
+You can dismiss a Popover by clicking the close icon or by pressing `Enter` or `Escape` keys.
+
+Focus always remains on the element that triggers the Popover; its content should not accept focus.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Normal
+
+In this example a Button is the trigger and simple text is displayed in the Popover.
+
+```jsx
+import { Popover } from "@simplybusiness/mobius";
+
+return (
+  <Popover
+    trigger={<Button variant="primary">If only I had more information</Button>}
+  >
+    No way! Now I know everything I need to 🚀.
+  </Popover>
+);
+```
+
+<Story of={PopoverStories.Normal} />
+
+## QCP Covers
+
+This is a customised trigger as used in the Quote Comparison Page, which has a large, clickable trigger (text and icon), but a small target for aligning the Popover arrow (just the icon).
+
+To achieve this, you need to control `isOpen` state with the clickable element and only use Popover to wrap the element you want to align with.
+
+```jsx
+import { Popover, Button, Flex } from "@simplybusiness/mobius";
+
+const [isOpen, setIsOpen] = useState<boolean>(false);
+const handleClick = () => setIsOpen(!isOpen);
+
+// Component passed to trigger prop must be wrapped with forwardRef()
+const Icon = forwardRef(
+  (props: IconProps, ref: Ref<SVGSVGElement>) => (
+    <svg ref={ref} {...props}>...</svg>
+  ),
+);
+
+return (
+  <Button variant="ghost" onClick={handleClick}>
+    <Flex>
+      <span>Occurrence Limit</span>
+      <Popover isOpen={isOpen} trigger={<Icon />}>
+        This is the maximum amount of money you&apos;ll get to cover a single
+        incident that occurs during the policy period, regardless of when
+        it&apos;s reported.
+      </Popover>
+    </Flex>
+  </Button>
+);
+```
+
+<Canvas of={PopoverStories.QCP} />
+
+## Props
+
+<ArgTypes of={Popover} />
+
+## Component HTML Structure and Class names
+
+The following HTML is rendered for Popover toggle:
+
+```html
+<button class="mobius/PopoverToggle">If only I had more information</button>
+```
+
+Popover content:
+
+```html
+<div class="mobius mobius/PopoverContainer">
+  <div class="mobius/Popover">
+    <header class="mobius/PopoverHeader">
+      <button class="mobius/PopoverCloseButton" aria-label="Close">
+        <svg class="mobius/PopoverCloseIcon">...</svg>
+      </button>
+    </header>
+    <div class="mobius/PopoverBody">
+      No way! Now I know everything I need to 🚀.
+    </div>
+  </div>
+</div>
+```
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Popover) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)

package/src/components/Popover/Popover.stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta } from "@storybook/react";
+import { Ref, forwardRef, useState } from "react";
+import { Button, Flex, Popover, PopoverProps } from "..";
+import { excludeControls } from "../../utils/excludeControls";
+
+export default {
+  title: "Components/Popover",
+  component: Popover,
+  argTypes: {
+    isOpen: {
+      control: { type: "boolean" },
+    },
+    ...excludeControls(
+      "className",
+      "children",
+      "trigger",
+      "id",
+      "onOpen",
+      "onClose",
+    ),
+  },
+  decorators: [
+    Story => {
+      // eslint-disable-next-line global-require
+      require("./Popover.story.styles.css");
+
+      return <Story />;
+    },
+  ],
+} satisfies Meta<typeof Popover>;
+
+type QuestionIconProps = {};
+
+const QuestionIcon = forwardRef(
+  (props: QuestionIconProps, ref: Ref<SVGSVGElement>) => (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      width="16px"
+      height="16px"
+      ref={ref}
+      {...props}
+    >
+      <g clipPath="url(#clip0_1641_88567)">
+        <path
+          d="M6.25 6.25002C6.25017 5.36011 6.91818 4.61203 7.80241 4.51155C8.68663 4.41107 9.50546 4.99019 9.7053 5.85737C9.90515 6.72456 9.42235 7.60364 8.58333 7.90027C8.23357 8.02393 7.99981 8.35471 8 8.72569V9.31253"
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <path
+          d="M8 11.0625C7.87919 11.0625 7.78125 11.1604 7.78125 11.2812C7.78125 11.4021 7.87919 11.5 8 11.5C8.12081 11.5 8.21875 11.4021 8.21875 11.2812C8.21875 11.1604 8.12081 11.0625 8 11.0625V11.0625"
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+        <circle cx="8" cy="8" r="6.5625" stroke="currentColor" />
+      </g>
+      <defs>
+        <clipPath id="clip0_1641_88567">
+          <rect width="16" height="16" fill="white" />
+        </clipPath>
+      </defs>
+    </svg>
+  ),
+);
+
+export const Normal: Meta<typeof Popover> = {
+  render: (args: PopoverProps) => <Popover {...args} />,
+  args: {
+    isOpen: undefined,
+    children: <>No way! Now I know everything I need to 🚀.</>,
+    trigger: <Button variant="primary">If only I had more information</Button>,
+  },
+};
+
+export const QCP: Meta<typeof Popover> = {
+  render: (args: PopoverProps) => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [isOpen, setIsOpen] = useState<boolean>(false);
+    const handleClick = () => setIsOpen(!isOpen);
+    return (
+      <div className="popover-example">
+        <Button variant="ghost" onClick={handleClick}>
+          <Flex>
+            <span>Occurrence Limit</span>
+            <Popover {...args} isOpen={isOpen} />
+          </Flex>
+        </Button>
+      </div>
+    );
+  },
+  args: {
+    trigger: <QuestionIcon />,
+    children: (
+      <>
+        This is the maximum amount of money you&apos;ll get to cover a single
+        incident that occurs during the policy period, regardless of when
+        it&apos;s reported.
+      </>
+    ),
+  },
+};

package/src/components/Popover/Popover.story.styles.css

@@ -0,0 +1,25 @@
+.popover-example {
+  max-width: 500px;
+  margin: 0 auto;
+}
+
+.popover-example .mobius\/Button {
+  border: none;
+  padding: 0;
+  font-weight: var(--font-weight-normal);
+  font-size: var(--font-size-2);
+  color: var(--color-neutral-700);
+  background-color: transparent;
+}
+
+.popover-example .mobius\/Button span {
+  text-decoration: underline;
+  text-decoration-style: dotted;
+  text-underline-offset: 6px;
+  margin-bottom: 6px;
+}
+
+.popover-example .mobius\/PopoverToggle {
+  width: 16px;
+  margin-left: 4px;
+}

package/src/components/Popover/Popover.test.tsx

@@ -0,0 +1,186 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { Popover } from ".";
+
+const CONTAINER_ID = "react-tiny-popover-container";
+const CONTAINER_CLASS_NAME = "mobius/PopoverContainer";
+const TOGGLE_CLASS_NAME = "mobius/PopoverToggle";
+const POPOVER_CLASS_NAME = "mobius/Popover";
+const HEADER_CLASS_NAME = "mobius/PopoverHeader";
+const CLOSE_BUTTON_CLASS_NAME = "mobius/PopoverCloseButton";
+const CLOSE_ICON_CLASS_NAME = "mobius/PopoverCloseIcon";
+const BODY_CLASS_NAME = "mobius/PopoverBody";
+
+describe("Popover", () => {
+  it("should render without errors", () => {
+    const component = render(
+      <Popover trigger={<button type="button">Click me</button>}>
+        Sample Text
+      </Popover>,
+    );
+
+    expect(component).toBeTruthy();
+  });
+
+  it("should open when clicked", async () => {
+    const sampleText = "Sample Text";
+    const triggerText = "Click me";
+
+    render(
+      <Popover trigger={<button type="button">{triggerText}</button>}>
+        {sampleText}
+      </Popover>,
+    );
+
+    const button = screen.getByText(triggerText);
+
+    fireEvent.click(button);
+
+    await waitFor(() => {
+      expect(screen.queryByText(sampleText)).toBeInTheDocument();
+    });
+
+    const closeButton = screen.getByLabelText("Close");
+
+    fireEvent.click(closeButton);
+
+    expect(screen.queryByText(sampleText)).not.toBeInTheDocument();
+  });
+
+  describe("uses correct class names", () => {
+    it("uses correct classes", async () => {
+      const sampleText = "Sample Text";
+      const triggerText = "Click me";
+
+      render(
+        <Popover trigger={<button type="button">{triggerText}</button>}>
+          {sampleText}
+        </Popover>,
+      );
+
+      const button = screen.getByText(triggerText);
+
+      expect(button).toHaveClass(TOGGLE_CLASS_NAME);
+
+      fireEvent.click(button);
+
+      const popoverContainer = document.querySelector(`#${CONTAINER_ID}`)
+        ?.firstChild;
+
+      await waitFor(() => {
+        expect(popoverContainer).toHaveClass("mobius");
+      });
+
+      const closeButton = screen.getByLabelText("Close");
+      const body = screen.getByText(sampleText);
+
+      expect(popoverContainer).toHaveClass(CONTAINER_CLASS_NAME);
+      expect(popoverContainer?.firstChild).toHaveClass(POPOVER_CLASS_NAME);
+      expect(closeButton.parentElement).toHaveClass(HEADER_CLASS_NAME);
+      expect(closeButton).toHaveClass(CLOSE_BUTTON_CLASS_NAME);
+      expect(closeButton.firstChild).toHaveClass(CLOSE_ICON_CLASS_NAME);
+      expect(body).toHaveClass(BODY_CLASS_NAME);
+    });
+
+    it("includes custom class name", async () => {
+      const customClassName = "my-class";
+      const sampleText = "Sample Text";
+      const triggerText = "Click me";
+
+      render(
+        <Popover
+          className={customClassName}
+          trigger={<button type="button">{triggerText}</button>}
+        >
+          {sampleText}
+        </Popover>,
+      );
+
+      const button = screen.getByText(triggerText);
+
+      fireEvent.click(button);
+
+      const popoverContainer = document.querySelector(`#${CONTAINER_ID}`);
+
+      await waitFor(() => {
+        expect(popoverContainer?.firstChild).toHaveClass(customClassName);
+      });
+    });
+  });
+
+  describe("events", () => {
+    describe("given isOpen prop is set", () => {
+      it("should not call onOpen or onClose when first rendered", () => {
+        const sampleText = "Sample Text";
+        const triggerText = "Click me";
+        const onOpen = jest.fn();
+        const onClose = jest.fn();
+
+        render(
+          <Popover
+            isOpen={false}
+            trigger={<button type="button">{triggerText}</button>}
+            onOpen={onOpen}
+            onClose={onClose}
+          >
+            {sampleText}
+          </Popover>,
+        );
+
+        expect(onOpen).not.toHaveBeenCalled();
+        expect(onClose).not.toHaveBeenCalled();
+      });
+    });
+
+    it("calls onOpen when Popover is opened", () => {
+      const sampleText = "Sample Text";
+      const triggerText = "Click me";
+      const onOpen = jest.fn();
+      const onClose = jest.fn();
+
+      render(
+        <Popover
+          trigger={<button type="button">{triggerText}</button>}
+          onOpen={onOpen}
+          onClose={onClose}
+        >
+          {sampleText}
+        </Popover>,
+      );
+
+      const button = screen.getByText(triggerText);
+
+      fireEvent.click(button);
+
+      expect(onOpen).toHaveBeenCalled();
+      expect(onClose).not.toHaveBeenCalled();
+    });
+
+    it("calls onClose when Popover is closed", () => {
+      const sampleText = "Sample Text";
+      const triggerText = "Click me";
+      const onOpen = jest.fn();
+      const onClose = jest.fn();
+
+      render(
+        <Popover
+          trigger={<button type="button">{triggerText}</button>}
+          onOpen={onOpen}
+          onClose={onClose}
+        >
+          {sampleText}
+        </Popover>,
+      );
+
+      const button = screen.getByText(triggerText);
+
+      fireEvent.click(button);
+
+      const closeButton = screen.getByLabelText("Close");
+
+      fireEvent.click(closeButton);
+
+      expect(onClose).toHaveBeenCalled();
+      expect(onOpen).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,137 @@
+import { cross } from "@simplybusiness/icons";
+import {
+  ReactElement,
+  ReactNode,
+  Ref,
+  RefAttributes,
+  cloneElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import classNames from "classnames";
+import { Popover as TinyPopover } from "react-tiny-popover";
+import { useWindowEvent } from "../../hooks";
+import { DOMProps } from "../../types/dom";
+import { Button } from "../Button";
+import { Icon } from "../Icon";
+
+export type PopoverElementType = HTMLDivElement;
+
+export interface PopoverProps
+  extends DOMProps,
+    RefAttributes<PopoverElementType> {
+  children?: ReactNode;
+  trigger: ReactElement;
+  isOpen?: boolean;
+  /** Callback that fires each time the accordion is opened */
+  onOpen?: () => void;
+  /** Callback that fires each time the accordion is closed */
+  onClose?: () => void;
+  /** Custom class name for setting specific CSS */
+  className?: string;
+}
+
+export type PopoverRef = Ref<PopoverElementType>;
+
+export const Popover = (props: PopoverProps) => {
+  const popoverRef = useRef(null);
+  const triggerRef = useRef(null);
+  const { trigger, children, isOpen, onOpen, onClose, className } = props;
+  const previousIsOpen = useRef<boolean | undefined>(isOpen);
+  const hasExternalState = typeof isOpen !== "undefined";
+  const [open, setOpen] = useState(isOpen);
+  const containerClasses = classNames(
+    "mobius",
+    "mobius/PopoverContainer",
+    className,
+  );
+  const noop = () => {};
+
+  const openPopover = useCallback(() => {
+    setOpen(true);
+
+    if (onOpen) {
+      onOpen();
+    }
+  }, [onOpen]);
+
+  const closePopover = useCallback(() => {
+    setOpen(false);
+
+    if (onClose) {
+      onClose();
+    }
+  }, [onClose]);
+
+  const handleClick = () => {
+    if (open) {
+      closePopover();
+      return;
+    }
+
+    openPopover();
+  };
+
+  const triggerComponent = cloneElement(trigger, {
+    className: "mobius/PopoverToggle",
+    onClick: hasExternalState ? noop : handleClick,
+  });
+
+  useWindowEvent("keydown", e => {
+    if (open && e.key === "Escape") {
+      closePopover();
+    }
+  });
+
+  useEffect(() => {
+    if (isOpen) {
+      openPopover();
+      return;
+    }
+
+    // Prevent 'onClose' being called when
+    // 'isOpen === false' on initial render
+    if (previousIsOpen.current === isOpen) {
+      previousIsOpen.current = undefined;
+      return;
+    }
+
+    if (!isOpen) {
+      closePopover();
+    }
+  }, [isOpen, closePopover, openPopover]);
+
+  return (
+    <TinyPopover
+      isOpen={!!open}
+      positions={["bottom"]}
+      ref={triggerRef}
+      content={
+        <div className={containerClasses} ref={popoverRef}>
+          <div className="mobius/Popover">
+            <header className="mobius/PopoverHeader">
+              <Button
+                type="button"
+                className="mobius/PopoverCloseButton"
+                onClick={handleClick}
+                aria-label="Close"
+                variant="ghost"
+              >
+                <Icon
+                  icon={cross}
+                  size="md"
+                  className="mobius/PopoverCloseIcon"
+                />
+              </Button>
+            </header>
+            <div className="mobius/PopoverBody">{children}</div>
+          </div>
+        </div>
+      }
+    >
+      {triggerComponent}
+    </TinyPopover>
+  );
+};

package/src/components/Popover/index.tsx

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

package/src/components/index.tsx

@@ -23,12 +23,13 @@ export * from "./Modal";
 export * from "./NumberField";
 export * from "./Option";
 export * from "./PasswordField";
+export * from "./Popover";
 export * from "./Progress";
 export * from "./Radio";
-export * from "./SVG";
 export * from "./Segment";
 export * from "./Select";
 export * from "./Slider";
+export * from "./SVG";
 export * from "./Table";
 export * from "./Text";
 export * from "./TextArea";