@hyphen/hyphen-components 2.9.0

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

@@ -0,0 +1,128 @@
+import React from 'react';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import { Placement } from '@popperjs/core';
+import { Popover } from './Popover';
+
+describe('Popover', () => {
+  describe('Default', () => {
+    it('Renders a popover with default props', async () => {
+      // NOTE: popperJS is throwing a warning due to missing act, but it is unclear how to fix these.
+      // https://github.com/popperjs/react-popper/issues/368
+      render(
+        <Popover isOpen content={<>hello</>}>
+          <p>trigger</p>
+        </Popover>
+      );
+
+      const popoverContent = screen.getByText('hello');
+      const popoverContainer = screen.getByRole('dialog');
+      const trigger = screen.getByText('trigger');
+      expect(popoverContent).toBeInTheDocument();
+      expect(trigger).toBeInTheDocument();
+      expect(trigger).toHaveAttribute('role', 'button');
+      expect(popoverContainer).toBeInTheDocument();
+      expect(popoverContainer).toHaveAttribute('role', 'dialog');
+      expect(popoverContainer).toHaveAttribute('aria-hidden', 'false');
+      expect(popoverContainer).toHaveClass('background-color-primary');
+      expect(popoverContainer).toHaveClass('p-sm');
+      await waitFor(() =>
+        expect(popoverContainer).toHaveAttribute(
+          'data-popper-placement',
+          'right'
+        )
+      );
+    });
+  });
+
+  describe('Callbacks', () => {
+    it('Fires a callback when a user clicks outside the popover', () => {
+      const mockedOnClickOutside = jest.fn();
+      const { container } = render(
+        <Popover
+          isOpen
+          content={<>hello</>}
+          onClickOutside={mockedOnClickOutside}
+        >
+          <p>trigger</p>
+        </Popover>
+      );
+
+      const popover = screen.getByText('hello');
+      const trigger = screen.getByText('trigger');
+      expect(popover).toBeInTheDocument();
+      fireEvent.click(popover);
+      fireEvent.click(trigger);
+      fireEvent.click(container);
+      fireEvent.keyUp(container, { key: 'Escape' });
+      expect(mockedOnClickOutside).toBeCalledTimes(2);
+    });
+  });
+
+  describe('Placement', () => {
+    // We do not test auto placements since those compute out to one of the below after detection.
+    const positions: Placement[] = [
+      'top',
+      'bottom',
+      'right',
+      'left',
+      'top-start',
+      'top-end',
+      'bottom-start',
+      'bottom-end',
+      'right-start',
+      'right-end',
+      'left-start',
+      'left-end',
+    ];
+
+    positions.forEach((position) => {
+      it(`Places the tooltop correctly in position: ${position} when prop is passed`, async () => {
+        render(
+          <Popover isOpen content={<>hello</>} placement={position}>
+            <p>trigger</p>
+          </Popover>
+        );
+
+        const popoverContainer = screen.getByRole('dialog');
+        await waitFor(() =>
+          expect(popoverContainer).toHaveAttribute(
+            'data-popper-placement',
+            position
+          )
+        );
+      });
+    });
+  });
+
+  describe('Portal', () => {
+    it('Renders the Popover in the body if withPortal is true.', async () => {
+      render(
+        <>
+          <div id="nest1">
+            <div id="nest2">
+              <Popover
+                isOpen
+                content={
+                  <button type="button" id="inside-button">
+                    hello
+                  </button>
+                }
+                withPortal
+                portalTarget={document.body}
+              >
+                <p>trigger</p>
+              </Popover>
+            </div>
+          </div>
+        </>
+      );
+
+      await waitFor(() => {
+        expect(document.body.children[1]).toHaveAttribute(
+          'data-popper-placement',
+          'right'
+        );
+      });
+    });
+  });
+});

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,277 @@
+import React, {
+  cloneElement,
+  FC,
+  isValidElement,
+  ReactNode,
+  useEffect,
+  useRef,
+  useState,
+  RefObject,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { usePopper } from 'react-popper';
+import { Placement } from '@popperjs/core';
+import FocusTrap from 'focus-trap-react';
+import classNames from 'classnames';
+import { BackgroundColor } from '../../types';
+import styles from './Popover.module.scss';
+import { Box, BoxProps } from '../Box/Box';
+import { mergeRefs } from '../../lib';
+
+export type PopoverProps = {
+  /**
+   * Custom class to apply to the alert.
+   */
+  className?: string;
+  /**
+   * The trigger element
+   */
+  children: ReactNode;
+  /**
+   * Content of the tooltip. Can be any JSX node.
+   */
+  content: ReactNode;
+  /**
+   * The Popover is a controlled input, and will be shown when `isOpen === true`.
+   */
+  isOpen: boolean;
+  /**
+   * Color of the arrow background. NOTE: That the arrowColor will default to the
+   * `background` color applied in the `contentContainerProps`, but can be overwritten
+   * by passing a specific value here.
+   */
+  arrowColor?: BackgroundColor;
+  /**
+   * An object matching the interface of the `Box` component props.
+   * This is useful for styling the tooltip container using all the options available in
+   * a `Box`.
+   */
+  contentContainerProps?: BoxProps;
+  /**
+   * Whether the arrow is shown.
+   */
+  hasArrow?: boolean;
+  /**
+   * How far (in pixels) the Popover element will be from the target.
+   * Note that this is from the edge of the target to the edge of the popover content,
+   * and it DOES NOT include the arrow element.
+   */
+  offsetFromTarget?: number;
+  /**
+   * Callback function to handle when a user clicks outside the Popover
+   */
+  onClickOutside?: (event: MouseEvent | KeyboardEvent) => void;
+  /**
+   * The placement (position) of the Popover relative to its trigger.
+   */
+  placement?: Placement;
+  /**
+   * Whether you want to trap focus in the Popover element when it is open.
+   * Read more about focus traps:
+   * [Here](https://allyjs.io/tutorials/accessible-dialog.html#trapping-focus-inside-the-dialog)
+   */
+  trapFocus?: boolean;
+  /**
+   * Additional props to be spread to rendered element
+   */
+  [x: string]: any; // eslint-disable-line
+} & (
+  | {
+      /**
+       * Whether the element should be rendered outside its DOM structure
+       * for reasons of placement. Use this when the element is being cut-off or
+       * re-positioned due to lack of space in the parent container.
+       * NOTE: `portalTarget` is required if this is true.
+       */
+      withPortal: true;
+      /**
+       * The target element where the Popover will be portaled to, when `withPortal === true`.
+       * `document.body` will work for many cases, but you can also use a custom container for this.
+       * Only required if withPortal is true.
+       */
+      portalTarget: HTMLElement;
+    }
+  | {
+      withPortal?: false;
+      portalTarget?: never;
+    }
+);
+
+const contentContainerDefaults: BoxProps = {
+  background: 'primary',
+  padding: 'sm',
+  radius: 'sm',
+  shadow: 'md',
+};
+
+export const Popover: FC<PopoverProps> = ({
+  className,
+  isOpen,
+  children,
+  content,
+  arrowColor = undefined,
+  contentContainerProps = { ...contentContainerDefaults },
+  hasArrow = true,
+  offsetFromTarget = 12,
+  onClickOutside = undefined,
+  placement = 'right',
+  withPortal = false,
+  portalTarget,
+  trapFocus = false,
+  ...restProps
+}) => {
+  const triggerRef = useRef<HTMLElement>(null);
+  const popperRef = useRef<HTMLElement>(null);
+  const [arrowElement, setArrowElement] = useState<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      const popover = popperRef.current;
+      const trigger = triggerRef.current;
+
+      if (!popover || !trigger) {
+        return;
+      }
+
+      if (event.target === trigger || trigger?.contains(event.target as Node)) {
+        return;
+      }
+
+      if (
+        event.target !== popover &&
+        !popover?.contains(event.target as Node)
+      ) {
+        if (onClickOutside) onClickOutside(event);
+      }
+    };
+
+    const handleKeyUp = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        if (onClickOutside) onClickOutside(event);
+      }
+    };
+
+    if (onClickOutside) {
+      document.body.addEventListener('click', handleClickOutside, false);
+      document.body.addEventListener('keyup', handleKeyUp);
+    }
+
+    return () => {
+      if (onClickOutside) {
+        document.body.removeEventListener('click', handleClickOutside, false);
+        document.body.removeEventListener('keyup', handleKeyUp);
+      }
+    };
+  }, [onClickOutside]);
+
+  const { styles: popperStyles, attributes } = usePopper(
+    triggerRef.current,
+    popperRef.current,
+    {
+      placement,
+      modifiers: [
+        {
+          name: 'arrow',
+          options: { element: arrowElement },
+        },
+        {
+          name: 'offset',
+          options: {
+            offset: [0, offsetFromTarget],
+          },
+        },
+      ],
+    }
+  );
+
+  const containerBoxProps = {
+    ...contentContainerDefaults,
+    ...contentContainerProps,
+  };
+
+  const computedArrowColor = arrowColor || containerBoxProps.background;
+
+  const arrowClasses = classNames(
+    styles['popover-arrow'],
+    `background-color-${computedArrowColor}`,
+    {
+      'display-none': !hasArrow,
+    }
+  );
+
+  const renderPopperContent = () => {
+    const renderPopperBox = () => (
+      <Box
+        ref={popperRef}
+        className={classNames(styles.popover, className)}
+        style={popperStyles.popper}
+        role="dialog"
+        aria-label="Popover"
+        aria-hidden={!isOpen}
+        {...containerBoxProps}
+        {...attributes.popper}
+        {...restProps}
+      >
+        <div
+          ref={setArrowElement}
+          style={popperStyles.arrow}
+          className={arrowClasses}
+          data-popper-arrow
+        />
+        {content}
+      </Box>
+    );
+
+    return trapFocus ? (
+      <FocusTrap
+        active={isOpen}
+        focusTrapOptions={{
+          clickOutsideDeactivates: true,
+        }}
+      >
+        {renderPopperBox()}
+      </FocusTrap>
+    ) : (
+      renderPopperBox()
+    );
+  };
+
+  const childrenWithRef = React.Children.map(children, (child) => {
+    const childProps = {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ref: triggerRef as RefObject<HTMLElement> | ((instance: any) => void),
+      role: 'button',
+      'aria-expanded': isOpen,
+      'aria-haspopup': true,
+    };
+
+    // Merge local ref with any ref passed originally to child component.
+    // We have to cast with `as` so TS compiler doesn't complain since ReactNode/ReactChild types don't
+    // explicitly declare ref as a property in the object.
+    if ((child as ReactNode & { ref: any })?.ref) {
+      // eslint-disable-line @typescript-eslint/no-explicit-any
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      childProps.ref = mergeRefs([
+        (child as ReactNode & { ref: any })?.ref,
+        childProps.ref,
+      ]);
+    }
+
+    if (isValidElement(child)) {
+      return cloneElement(child, childProps);
+    }
+
+    return child;
+  });
+
+  return (
+    <>
+      {childrenWithRef}
+      {isOpen &&
+        // portalTarget should always be defined if withPortal is true, but better safe than sorry here!
+        (withPortal && portalTarget
+          ? createPortal(renderPopperContent(), portalTarget)
+          : renderPopperContent())}
+    </>
+  );
+};

package/src/components/RadioGroup/RadioGroup.mdx

@@ -0,0 +1,81 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { RadioGroup } from './RadioGroup';
+import * as Stories from './RadioGroup.stories';
+
+<Meta of={Stories} />
+
+# RadioGroup
+
+Use a RadioGroup when a user is required to select one of five or fewer options. It is ideal for this scenario because the options are displayed without having to interact. If there are more than five options, use the [SelectInput](?path=/docs/components-selectinput-overview--default-story) instead.
+
+## Props
+
+<ArgTypes of={RadioGroup} />
+
+## Default
+
+All that is required to render a basic version of the RadioGroup is the group's `name`, an onchange event handler passed to the `onChange` prop, and a list of options passed to the `options` prop. Each option must include a unique `id`, a `value`, and a `label`.
+
+<Canvas isExpanded of={Stories.Default} />
+
+## Title
+
+Use the `title` prop to add a title.
+
+<Canvas of={Stories.Title} />
+
+## Title and Description
+
+Use the `title` and `description` props to add a title and description.
+
+<Canvas of={Stories.TitleAndDescription} />
+
+## Required
+
+Use the `isRequired` prop to mark the group as requiring at least one selection. To avoid confusion as to whether a radio button group is required or not, authors are encouraged to specify the attribute on all the radio buttons in a group. We recommend to avoid having radio button groups that do not have any initially checked controls in the first place, because this is a state that the user cannot return to.
+
+<Canvas of={Stories.Required} />
+
+You can remove or customize the required indicator using the `requiredIndicator` prop.
+
+<Canvas of={Stories.CustomRequiredIndicator} />
+
+## Pre-Selected Option
+
+Use the `value` prop to pre-select an option.
+
+<Canvas of={Stories.PreSelectedOption} />
+
+## Disabled Option
+
+An individual option, or multiple options can be disabled by marking them as disabled in the list of options.
+
+<Canvas of={Stories.DisabledOption} />
+
+## Disabled Group
+
+A group can be fully disabled by using the `isDisabled` prop.
+
+<Canvas of={Stories.DisabledGroup} />
+
+## Error
+
+Use the `error` prop to mark the input as invalid. `error` accepts a `boolean`, `string`, or `node`. If either a `string` or `node` is passed, a validation message is displayed below it.
+
+<Canvas of={Stories.Error} />
+
+## Sizes
+
+Use the `size` prop to render differently sized radio icons.
+
+<Canvas of={Stories.Sizes} />
+
+## Horizontally Aligned
+
+Use the `direction` prop change the alignment of the radio inputs.
+
+<Canvas of={Stories.HorizontallyAligned} />
+
+## Component Design Tokens
+
+This component shares component design tokens with all form controls. For a complete list of tokens, see the [Theming Form Controls documentation](/docs/theming-form-controls--custom-theme-form).

package/src/components/RadioGroup/RadioGroup.module.scss

@@ -0,0 +1,23 @@
+.radio-group {
+  .fieldset {
+    margin: 0;
+    border: none;
+    padding: 0;
+    font-family: var(--form-control-font-family, var(--INTERNAL_form-control-font-family));
+
+    .legend {
+      display: block;
+      margin-bottom: var(--form-control-radio-group-options-spacing, var(--INTERNAL_form-control-radio-group-options-spacing));
+      line-height: 1.25;
+      color: var(--form-control-font-color, var(--INTERNAL_form-control-font-color));
+      font-size: var(--form-control-size-md-label-size, var(--INTERNAL_form-control-size-md-label-size));
+      font-weight: var(--form-control-legend-font-weight, var(--INTERNAL_form-control-legend-font-weight));
+
+      .description {
+        margin-top: var(--INTERNAL_form-control-radio-group-description-spacing, var(--INTERNAL_form-control-radio-group-description-spacing));
+        color: var(--form-control-description-color, var(--INTERNAL_form-control-description-color));
+        font-weight: 400;
+      }
+    }
+  }
+}