@hyphen/hyphen-components 2.9.0

package/src/components/Drawer/Drawer.test.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { Drawer, DrawerProps } from './Drawer';
+
+const renderDrawer = ({
+  isOpen,
+  title,
+  ariaLabel,
+  onDismiss,
+  closeButton,
+}: DrawerProps) => (
+  <Drawer
+    isOpen={isOpen}
+    title={title}
+    ariaLabel={ariaLabel}
+    onDismiss={onDismiss}
+    closeButton={closeButton}
+  />
+);
+
+describe('Drawer', () => {
+  test('renders its children', () => {
+    const { getByText } = render(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: true,
+        title: 'Right Drawer',
+        onDismiss: () => null,
+      })
+    );
+    expect(getByText('Right Drawer')).toBeInTheDocument();
+  });
+
+  test('it applies the aria label', () => {
+    const { getByLabelText } = render(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: true,
+        title: 'Right Drawer',
+        onDismiss: () => null,
+      })
+    );
+    expect(getByLabelText('Right Drawer')).toBeInTheDocument();
+  });
+
+  test('it renders a close button and title', () => {
+    const { getByText, getByLabelText } = render(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: true,
+        title: 'Right Drawer',
+        onDismiss: () => null,
+      })
+    );
+    expect(getByLabelText('close')).toBeInTheDocument();
+    expect(getByText('Right Drawer')).toBeInTheDocument();
+  });
+
+  test('it renders a close button without title', () => {
+    const { getByLabelText } = render(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: true,
+        onDismiss: () => null,
+        closeButton: true,
+      })
+    );
+    expect(getByLabelText('close')).toBeInTheDocument();
+  });
+
+  test('it open and closes based on isOpen prop', () => {
+    const { queryByLabelText, getByLabelText, rerender } = render(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: false,
+      })
+    );
+
+    expect(queryByLabelText('Right Drawer')).toBe(null);
+
+    rerender(
+      renderDrawer({
+        ariaLabel: 'Right Drawer',
+        isOpen: true,
+      })
+    );
+
+    expect(getByLabelText('Right Drawer')).toBeInTheDocument();
+  });
+});

package/src/components/Drawer/Drawer.tsx

@@ -0,0 +1,249 @@
+import React, {
+  CSSProperties,
+  RefObject,
+  forwardRef,
+  useCallback,
+} from 'react';
+import ReactModal from 'react-modal';
+import FocusLock from 'react-focus-lock';
+import { RemoveScroll } from 'react-remove-scroll';
+import classNames from 'classnames';
+import { DimensionSize, CssDimensionValue } from '../../types';
+import { Box } from '../Box/Box';
+import styles from './Drawer.module.scss';
+import { Button } from '../Button/Button';
+
+export type DrawerPlacementType = 'left' | 'right' | 'top' | 'bottom';
+export interface DrawerProps {
+  /**
+   * If the drawer is open
+   */
+  isOpen: boolean;
+  /**
+   * Handle zoom/pinch gestures on iOS devices when scroll locking is enabled.
+   */
+  allowPinchZoom?: boolean;
+  /**
+   * A drawer needs to be properly labeled to provide context for users with
+   * assistive technology such as screen readers. If a drawer is announced to
+   * the user without a label, it can be confusing and difficult to navigate.
+   */
+  ariaLabel?: string;
+  /**
+   * The id of the element that should be used as the drawer's label by assistive technologies like screen readers.
+   */
+  ariaLabelledBy?: string;
+  /**
+   * Contents of the dialog.
+   */
+  children?: React.ReactNode;
+  /**
+   * Additional class names to add to the drawer content.
+   */
+  className?: string;
+  /**
+   * Whether the drawer has a visible close button.
+   * If a title is defined, then a close button will be rendered
+   */
+  closeButton?: boolean;
+  /**
+   * If true, the drawer will close when the overlay is clicked
+   */
+  closeOnOverlayClick?: boolean;
+  /**
+   * The ref of the container where the drawer will be inserted into the DOM.
+   * By default, drawers are inserted in the document.body, but if need be they can
+   * be scoped as necessary.
+   */
+  containerRef?: React.RefObject<Node>;
+  /**
+   * By default, focus is trapped within the drawer.
+   * If true, focus will not be trapped within the contents of the drawer.
+   */
+  dangerouslyBypassFocusLock?: boolean;
+  /**
+   * By default, the drawer locks scrolling on the body, but in some cases you may want to allow for scrolling.
+   * If true, this will allow the body to scroll while the drawer is open.
+   */
+  dangerouslyBypassScrollLock?: boolean;
+  /**
+   * If true, the overlay will not be rendered, scrolling for the entire page will remain enabled,
+   * and focus will not be locked to the contents of the drawer
+   */
+  hideOverlay?: boolean;
+  /**
+   * By default the first focusable element will receive focus when the dialog
+   * opens but you can provide a ref to focus instead.
+   *
+   * @see Docs https://reach.tech/dialog#dialog-initialfocusref
+   */
+  initialFocusRef?: RefObject<HTMLDivElement>;
+  /**
+   * Which edge of the viewport should the drawer appear from
+   */
+  placement?: DrawerPlacementType;
+  /**
+   * Function that is called whenever the user either hits
+   *  the "Escape" key, clicks the close button icon, or clicks the overlay.
+   */
+  onDismiss?: (event?: React.SyntheticEvent) => void;
+  /**
+   * Title to be displayed at the top of the Drawer.
+   * A close button will be rendered automatically if this prop is defined.
+   */
+  title?: string;
+  /**
+   * The width of the Drawer when opened. Can be given a standard css value (px, rem, em, %),
+   * or a [width token](/?path=/story/design-tokens-design-tokens--page#width)
+   */
+  width?: DimensionSize | CssDimensionValue;
+}
+export const Drawer: React.FC<DrawerProps> = forwardRef<
+  HTMLDivElement,
+  DrawerProps
+>(
+  (
+    {
+      ariaLabel = undefined,
+      ariaLabelledBy = undefined,
+      allowPinchZoom = false,
+      children = undefined,
+      className = undefined,
+      closeButton = false,
+      closeOnOverlayClick = true,
+      containerRef = undefined,
+      dangerouslyBypassFocusLock = false,
+      dangerouslyBypassScrollLock = false,
+      hideOverlay = false,
+      initialFocusRef = undefined,
+      isOpen,
+      onDismiss = undefined,
+      placement = 'right',
+      title = undefined,
+      width = undefined,
+    },
+    ref
+  ) => {
+    const activateFocusLock = useCallback(() => {
+      setTimeout(() => {
+        if (initialFocusRef && initialFocusRef.current) {
+          initialFocusRef.current.focus();
+        }
+      }, 100);
+    }, [initialFocusRef]);
+
+    const dynamicWidth = width;
+
+    const dynamicStyle: CSSProperties = {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ['--w' as any]: dynamicWidth,
+    };
+
+    const overlayClassnames = classNames(styles.overlay, styles.drawer, {
+      [styles['hide-overlay']]: hideOverlay,
+      [styles[`hide-overlay-${placement}`]]: hideOverlay,
+      'position-fixed': containerRef === undefined,
+      'position-absolute': containerRef !== undefined,
+    });
+
+    const contentClassnames = classNames(
+      styles['drawer-content'],
+      styles[placement],
+      {
+        [styles['hide-overlay']]: hideOverlay,
+        'overflow-auto': !closeButton && !title,
+        className,
+      }
+    );
+
+    const renderHeader = () => {
+      if (closeButton && onDismiss && !title) {
+        return (
+          <Box alignItems="flex-end" justifyContent="center" padding="md lg">
+            <Button
+              variant="tertiary"
+              onClick={onDismiss}
+              aria-label="close"
+              type="button"
+              iconPrefix="remove"
+            />
+          </Box>
+        );
+      }
+      if (title) {
+        return (
+          <Box
+            direction="row"
+            justifyContent="space-between"
+            alignItems="center"
+            padding="2xl"
+          >
+            <Box className={styles.title} fontWeight="bold">
+              {title}
+            </Box>
+            {onDismiss && (
+              <Button
+                variant="tertiary"
+                onClick={onDismiss}
+                aria-label="close"
+                type="button"
+                iconPrefix="remove"
+              />
+            )}
+          </Box>
+        );
+      }
+      return null;
+    };
+
+    const content =
+      title || closeButton ? (
+        <Box flex="auto" overflow="auto">
+          {children}
+        </Box>
+      ) : (
+        children
+      );
+
+    const parentElement = containerRef?.current
+      ? (containerRef.current as HTMLElement)
+      : document.body;
+
+    const isDisabledFocusLock = hideOverlay || dangerouslyBypassFocusLock;
+    const isDisabledRemoveScroll = hideOverlay || dangerouslyBypassScrollLock;
+
+    return (
+      <FocusLock
+        autoFocus
+        returnFocus
+        disabled={isDisabledFocusLock || !isOpen}
+        onActivation={activateFocusLock}
+      >
+        <RemoveScroll
+          allowPinchZoom={allowPinchZoom}
+          enabled={!isDisabledRemoveScroll && isOpen}
+        >
+          <Box ref={ref}>
+            <ReactModal
+              isOpen={isOpen}
+              overlayClassName={overlayClassnames}
+              className={contentClassnames}
+              onRequestClose={closeOnOverlayClick ? onDismiss : undefined}
+              ariaHideApp={false}
+              style={{
+                content: dynamicStyle,
+                overlay: dynamicStyle,
+              }}
+              parentSelector={() => parentElement}
+            >
+              <Box aria-label={ariaLabel} aria-labelledby={ariaLabelledBy}>
+                {renderHeader()}
+                {content}
+              </Box>
+            </ReactModal>
+          </Box>
+        </RemoveScroll>
+      </FocusLock>
+    );
+  }
+);

package/src/components/FormControl/FormControl.tsx

@@ -0,0 +1,78 @@
+import React, { ReactNode } from 'react';
+import { Box, BoxProps } from '../Box/Box';
+import { FormLabel } from '../FormLabel/FormLabel';
+import { InputValidationMessage } from '../InputValidationMessage/InputValidationMessage';
+
+export interface FormControlProps extends BoxProps {
+  /**
+   * The input's id attribute. Used to programmatically tie the input with its label.
+   */
+  id: string;
+  /**
+   * Custom content to be displayed above the input. If the label is hidden, will be used to set aria-label attribute.
+   */
+  label: string;
+  /**
+   * Mark the input field as invalid and display a validation message.
+   * Pass a string or node to render a validation message below the input.
+   */
+  error?: ReactNode;
+  /**
+   * Visually hide the label.
+   */
+  hideLabel?: boolean;
+  /**
+   * Additional clarifying text to help describe the input
+   */
+  helpText?: ReactNode;
+  /**
+   * The input's disabled attribute
+   */
+  isDisabled?: boolean;
+  /**
+   * The required and aria-required attributes on the input
+   */
+  isRequired?: boolean;
+  /**
+   * Visual indicator that the field is required, that gets appended to the label
+   */
+  requiredIndicator?: ReactNode;
+}
+
+export const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
+  (
+    {
+      label,
+      hideLabel,
+      children,
+      error,
+      id,
+      isRequired,
+      helpText,
+      isDisabled,
+      requiredIndicator,
+      width = '100',
+      ...restProps
+    },
+    ref
+  ) => {
+    const labelProps = {
+      inputId: id,
+      helpText,
+      margin: '0 0 xs 0',
+      isDisabled,
+      isFieldRequired: isRequired,
+      requiredIndicator,
+    };
+
+    return (
+      <Box width={width} ref={ref} {...restProps}>
+        {label && !hideLabel && <FormLabel {...labelProps}>{label}</FormLabel>}
+        {children}
+        {error && error !== true && (
+          <InputValidationMessage>{error}</InputValidationMessage>
+        )}
+      </Box>
+    );
+  }
+);

package/src/components/FormLabel/FormLabel.mdx

@@ -0,0 +1,24 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { FormLabel } from './FormLabel';
+import * as Stories from './FormLabel.stories';
+
+<Meta of={Stories} />
+
+# FormLabel
+
+FormLabel is a sub component of many of our inputs, and is meant to be paired with a form input. In most cases, the label will have already been built into another component as a prop. However, you can use it on its own or with another component.
+
+<Canvas of={Stories.BasicUsage} />
+
+## Accessibility
+
+- Each label requires the `inputId` prop that equals the id of the associated input so that the `htmlFor` property can be set.
+- Don't use placeholder text as a replacement for labels. It can be used to provide an example to users, but will disappear from the field when a user enters text. It's also not broadly supported by assistive technologies and won't display in older browsers.
+- Use one of 3 ways to label a form field in order of most preferred:
+  1. Visible label with Label
+  2. Visible label that's associated to the input with aria-labelledby
+  3. Label directly using aria-label
+
+## Props
+
+<ArgTypes of={FormLabel} />

package/src/components/FormLabel/FormLabel.module.scss

@@ -0,0 +1,19 @@
+.label {
+  font-family: var(--INTERNAL_form-control-font-family);
+  color: var(--color-font-base);
+  font-size: var(--INTERNAL_form-control-size-md-label-size);
+  font-weight: var(--INTERNAL_form-control-label-font-weight);
+
+  &.radio-input-label {
+    font-weight: 400;
+  }
+
+  &.disabled {
+    color: var(--color-base-grey-300);
+  }
+
+  .help-text {
+    margin-top: var(--INTERNAL_form-control-help-margin);
+    font-weight: var(--INTERNAL_form-control-help-font-weight);
+  }
+}

package/src/components/FormLabel/FormLabel.stories.tsx

@@ -0,0 +1,20 @@
+import { FormLabel } from './FormLabel';
+
+import type { Meta } from '@storybook/react';
+import React from 'react';
+
+const meta: Meta<typeof FormLabel> = {
+  title: 'Components/FormLabel',
+  component: FormLabel,
+  parameters: {
+    controls: { hideNoControlsWarning: true },
+  },
+};
+
+export default meta;
+
+export const BasicUsage = () => (
+  <FormLabel inputId="inputId" helpText="More helpful text about the input">
+    Default Label
+  </FormLabel>
+);

package/src/components/FormLabel/FormLabel.test.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { FormLabel } from './FormLabel';
+
+beforeEach(() => {
+  console.error = jest.fn(); // eslint-disable-line no-console
+});
+
+afterEach(() => {
+  (console.error as jest.Mock).mockRestore(); // eslint-disable-line no-console
+});
+
+describe('FormLabel', () => {
+  test('Label correctly renders with base props', () => {
+    render(<FormLabel inputId="myId">my label</FormLabel>);
+    const labelElement = screen.getByText('my label');
+    expect(labelElement).toHaveAttribute('for', 'myId');
+    expect(labelElement).toHaveTextContent('my label');
+  });
+
+  test('correctly assigns an id when given an inputId', () => {
+    render(<FormLabel inputId="myId">my label</FormLabel>);
+    const labelElement = screen.getByText('my label');
+    expect(labelElement).toHaveAttribute('id', 'myIdLabel');
+  });
+
+  test('renders help text if provided', () => {
+    const { getByText } = render(
+      <FormLabel inputId="myId" helpText="i am help text">
+        my label
+      </FormLabel>
+    );
+    expect(getByText('i am help text')).toBeDefined();
+  });
+});

package/src/components/FormLabel/FormLabel.tsx

@@ -0,0 +1,96 @@
+import React, { FC, ReactNode } from 'react';
+import classNames from 'classnames';
+import { Box, BoxProps } from '../Box/Box';
+import styles from './FormLabel.module.scss';
+
+export interface FormLabelProps extends BoxProps {
+  /**
+   * Content to be rendered inside the label.
+   */
+  children: ReactNode;
+  /**
+   * The id of the form control that the label is labeling
+   */
+  inputId: string;
+  /**
+   * Custom class to pass to label element.
+   */
+  className?: string;
+  /**
+   * Additional clarifying text to that helps describe the field
+   */
+  helpText?: ReactNode;
+  /**
+   * Mark the label has disabled
+   */
+  isDisabled?: boolean;
+  /**
+   * prop deprecated: no longer in use and will be remove in next major release.
+   */
+  isFieldRequired?: boolean;
+  /**
+   * Apply custom styling to labels for a radio input
+   */
+  isRadioInputLabel?: boolean;
+  /**
+   * Visual indicator that the field is required, that gets appended to the label
+   */
+  requiredIndicator?: ReactNode;
+  /**
+   * Additional props to be spread to rendered element
+   */
+  [x: string]: any; // eslint-disable-line
+}
+
+export const FormLabel: FC<FormLabelProps> = ({
+  children,
+  inputId,
+  className = '',
+  display = 'block',
+  helpText,
+  isDisabled = false,
+  isFieldRequired = false,
+  isRadioInputLabel = false,
+  requiredIndicator = ' *',
+  margin = '0',
+  padding = '0',
+  ...restProps
+}) => {
+  const labelClasses = classNames(
+    'hyphen-components__variables__form-control',
+    styles.label,
+    className,
+    {
+      [styles.disabled]: isDisabled,
+      [styles.disabled]: isDisabled,
+      [styles['radio-input-label']]: isRadioInputLabel,
+    }
+  );
+
+  return (
+    <Box
+      as="label"
+      id={`${inputId}Label`}
+      className={labelClasses}
+      display={display}
+      margin={margin}
+      padding={padding}
+      htmlFor={inputId}
+      {...restProps}
+    >
+      {children}
+      {isFieldRequired && requiredIndicator && <span>{requiredIndicator}</span>}
+      {helpText && (
+        <Box
+          as="p"
+          display="block"
+          fontSize="sm"
+          color="secondary"
+          className={styles['help-text']}
+        >
+          {helpText}
+        </Box>
+      )}
+    </Box>
+  );
+};

package/src/components/Formik/Formik.mdx

@@ -0,0 +1,10 @@
+import { Meta, Canvas } from '@storybook/addon-docs';
+import * as Stories from './Formik.stories';
+
+<Meta of={Stories} />
+
+# Formik Form
+
+Formik Form demonstrates a pattern for integrating the input elements found in Hyphen Components with [Formik](https://formik.org/). The form is fully functional and even mock submits. Manipulate the inputs in the form and watch the state object below it update with the new values in real-time. Attempt to submit the form without filling out required inputs, and observe the error states for these inputs.
+
+<Canvas of={Stories.FormikForm} />