@hyphen/hyphen-components 2.9.0

package/src/components/Details/Details.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import classNames from 'classnames';
+import { DetailsSummary } from './DetailsSummary';
+import styles from './Details.module.scss';
+import { Box, BoxProps } from '../Box/Box';
+
+export interface DetailsProps extends BoxProps {
+  /**
+   * Whether the details below the summary are opened. Directly corresponds to `open` property in <details> element.
+   */
+  isOpen: boolean;
+}
+
+export const DetailsBaseComponent: React.FC<DetailsProps> = React.forwardRef<
+  HTMLDetailsElement,
+  DetailsProps
+>(({ children, className, display = 'block', isOpen, ...restProps }, ref) => {
+  const detailsClasses = classNames(
+    className,
+    styles['details-reset'],
+    styles.details
+  );
+
+  return (
+    <Box
+      as="details"
+      className={detailsClasses}
+      display={display}
+      open={isOpen}
+      ref={ref}
+      {...restProps}
+    >
+      {children}
+    </Box>
+  );
+});
+
+export interface DetailsStatic {
+  Summary: typeof DetailsSummary;
+}
+
+export type DetailsWithStaticComponents = typeof DetailsBaseComponent &
+  DetailsStatic;
+
+// Actual component is wrapped in an IIFE for the export
+// To allow tree-shaking even with static properties (subcomponents in this case).
+export const Details = (() => {
+  const Details = DetailsBaseComponent as DetailsWithStaticComponents; // eslint-disable-line no-shadow
+  Details.Summary = DetailsSummary;
+  return Details;
+})();

package/src/components/Details/DetailsSummary.tsx

@@ -0,0 +1,65 @@
+import React, { MouseEvent, KeyboardEvent } from 'react';
+import { ENTER, SPACE } from '../../constants/keyCodes';
+import { Box, BoxProps } from '../Box/Box';
+
+export interface DetailsSummaryProps extends BoxProps {
+  isDetailsOpen: boolean;
+  onToggle?: (
+    event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>
+  ) => void;
+}
+
+export const DetailsSummary: React.FC<DetailsSummaryProps> = ({
+  children,
+  display = 'block',
+  isDetailsOpen,
+  onToggle,
+  ...restProps
+}) => {
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    // Needed to avoid default `details` behavior on a click event and keep this as controlled component.
+    event.preventDefault();
+
+    if (!onToggle && !restProps?.onClick) return;
+
+    if (onToggle) {
+      onToggle(event);
+    }
+
+    if (restProps?.onClick) {
+      restProps.onClick(event);
+    }
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if ([ENTER, SPACE].indexOf(event.keyCode) !== -1) {
+      // Needed to avoid default `details` behavior on a click event and keep this as controlled component.
+      event.preventDefault();
+    }
+
+    if (!onToggle && !restProps?.onKeyDown) return;
+
+    if (onToggle && [ENTER, SPACE].indexOf(event.keyCode) !== -1) {
+      onToggle(event);
+    }
+
+    if (restProps?.onKeyDown) {
+      restProps.onKeyDown(event);
+    }
+  };
+
+  return (
+    <Box
+      {...restProps}
+      as="summary"
+      display={display}
+      role="button"
+      aria-expanded={isDetailsOpen}
+      tabIndex={0}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+    >
+      {children}
+    </Box>
+  );
+};

package/src/components/Drawer/Drawer.mdx

@@ -0,0 +1,117 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { Drawer } from './Drawer';
+import { Alert } from '../Alert/Alert';
+import * as Stories from './Drawer.stories';
+
+<Meta of={Stories} />
+
+# Drawer
+
+A Drawer is a panel that slides in from one edge of the viewport and overlays content on top of the page. It contains information or actions without leaving the context of the original page.
+
+<Canvas withSource="open" of={Stories.BasicUsage} />
+
+## Usage Guidelines
+
+- Use the drawer as way to achieve progressive disclosure, to reveal relevant information at the appropriate time.
+- The Drawer visibility is controlled via the `isOpen` prop, and is hidden by default. To handle closing the Drawer, provide an `onDismiss` callback that will be called when the user clicks the Overlay or Esc keyboard key.
+- When a Drawer is open, the main body is scroll-locked by default.
+- Avoid nesting Drawers to prevent usability issues.
+- The button that triggers the drawer opening should be in close proximity to the Drawer itself.
+- Drawers are appropriate for supplemental information, filters, or subtasks where it's important to keep the subtasks in the context of the main task
+
+### When not to use
+
+- To force users to complete an action before continuing. Use a [Modal](/docs/components-modal--docs) instead.
+- For small content or a few options near the original content, use a [Popover](/docs/components-popover--docs).
+
+## Content Guidelines
+
+Drawers are good for short pieces of content that are related to the main screen but not a part of it. Examples include:
+
+- Contextual help
+- Notifications or activity log
+- Simple forms or settings
+- Navigation or page table of contents
+
+## Accessibility
+
+- Use the `ariaLabel` or `ariaLabelledBy` props to properly label a drawer 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.
+- When the Drawer is opened, focus is trapped inside the Drawer.
+- The 'Esc' key will close the Drawer.
+- After the drawer closes, focus is returned to the element that triggered it.
+
+## Props
+
+<ArgTypes of={Drawer} />
+
+## Placement
+
+The Drawer can appear from the right (default), left, top, or bottom of the screen. When appearing from the left or right of the screen, the close Icon Button is positioned on the same side where the Drawer originates from. When appearing from the top or bottom of the screen, the close Icon Button is positioned on the right as default.
+
+<Canvas withSource="open" of={Stories.Placement} />
+
+## Drawer Header
+
+A header will be added to the drawer content if `title` is defined, or `closeButton` is `true`. If the content of the drawer is taller than the drawer height, then the content will scroll while the header remains fixed to the top.
+
+<Canvas withSource="open" of={Stories.DrawerHeader} />
+
+## Title and Close Button
+
+<Canvas withSource="open" of={Stories.TitleAndCloseButton} />
+
+## Close Button Only
+
+<Canvas withSource="open" of={Stories.CloseButtonOnly} />
+
+## Width
+
+Set the width of a Drawer to specific value for a `left` or `right` placement via `width`. The Drawer height will be 100% of the viewport, or if `containerRef` is used, 100% of the container.
+
+When `placement` is set to `top` or `bottom`, the `width` prop is ignored and the drawer will be 100% of the viewport or container.
+
+<Canvas withSource="open" of={Stories.Width} />
+
+## Height
+
+The height of Drawers with a `top` or `bottom` placement is determined by Drawer's contents. The width will be set to 100%.
+
+<Canvas withSource="open" of={Stories.Height} />
+
+## Hidden Overlay
+
+In cases where content in the drawer is supplemental to content on the main area of the page, use `hideOverlay` to allow for interaction between the areas (e.g. copy-and-paste text from main area into a form in the drawer).
+
+<Alert
+  variant="warning"
+  title="Focus Management"
+  hasIcon
+  message="If you decide to use `hideOverlay`, then you must also manage focus. Focus and page scrolling will not be locked if `hideOverlay` is true. Also, the 'Esc' key button will no longer automatically close the Drawer."
+/>
+
+<Canvas withSource="open" of={Stories.HiddenOverlay} />
+
+## Initial Focus Ref
+
+By default the first focusable element will receive focus when the drawer opens, but you can provide a ref to focus instead.
+
+<Alert
+  hasIcon
+  message="Without the initialFocusRef prop, the drawer will automatically focus on the first focusable element in it's children."
+  variant="info"
+/>
+
+<Canvas withSource="open" of={Stories.InitialFocusRef} />
+
+## Contained Drawer
+
+Render the Drawer within a containing div using `containerRef`.
+
+<Alert
+  hasIcon
+  message="When choosing to use a Drawer within a containing div, use dangerouslyBypassScrollLock to allow the content outside of the containing div to remain interactive."
+  variant="info"
+/>
+
+<Canvas withSource="open" of={Stories.ContainedDrawer} />

package/src/components/Drawer/Drawer.module.scss

@@ -0,0 +1,96 @@
+@import '@hyphen/hyphen-design-tokens/build/scss/variables';
+
+.drawer {
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: var(--size-z-index-overlay);
+  background: hsl(0deg 0% 0% / 33%);
+  max-height: 100vh;
+  overflow: visible;
+
+  //for the hide-overlay-* classes, push the overlay to opposite edge so that underlying content is not covered
+  &.hide-overlay-right {
+    left: 100%;
+    background-color: transparent;
+  }
+
+  &.hide-overlay-left {
+    right: 100%;
+    background-color: transparent;
+  }
+
+  &.hide-overlay-bottom {
+    top: 100%;
+    background-color: transparent;
+  }
+
+  &.hide-overlay-top {
+    bottom: 100%;
+    background-color: transparent;
+  }
+
+  :global {
+    animation: fadeIn 0.2s;
+  }
+}
+
+.drawer {
+  .drawer-content {
+    background-color: var(--color-background-primary);
+    display: flex;
+    flex-direction: column;
+    padding: 0;
+    position: absolute;
+    box-shadow: var(--drawer-box-shadow, var(--size-box-shadow-xl));
+    z-index: var(--size-z-index-drawer);
+
+    &.left {
+      left: 0;
+      width: var(--w, 80vw);
+      height: 100%;
+
+      :global {
+        animation: fadeInRight 0.2s ease-out;
+      }
+    }
+
+    &.right {
+      right: 0;
+      width: var(--w, 80vw);
+      height: 100%;
+
+      :global {
+        animation: fadeInLeft 0.2s ease-out;
+      }
+    }
+
+    &.bottom {
+      bottom: 0;
+      width: 100%;
+      max-height: 100vh;
+
+      :global {
+        animation: fadeInUp 0.2s ease-out;
+      }
+    }
+
+    &.top {
+      top: 0;
+      width: 100%;
+      max-height: 100vh;
+
+      :global {
+        animation: fadeInDown 0.2s ease-out;
+      }
+    }
+
+    @media (min-width: $size-breakpoint-tablet) {
+      &.right,
+      &.left {
+        width: var(--w, var(--size-dimension-8xl));
+      }
+    }
+  }
+}

package/src/components/Drawer/Drawer.stories.tsx

@@ -0,0 +1,380 @@
+import { Drawer, DrawerPlacementType } from './Drawer';
+import type { Meta } from '@storybook/react';
+import React, { MutableRefObject, useEffect, useRef, useState } from 'react';
+import { useOpenClose } from '../../hooks';
+import { Button } from '../Button/Button';
+import { Box } from '../Box/Box';
+import { RadioGroup } from '../RadioGroup/RadioGroup';
+import { WidthSize } from '../../types';
+
+const meta: Meta<typeof Drawer> = {
+  title: 'Components/Drawer',
+  component: Drawer,
+};
+
+export default meta;
+
+export const BasicUsage = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Open Drawer
+      </Button>
+      <Drawer
+        isOpen={isDrawerOpen}
+        title="Drawer Title"
+        onDismiss={closeDrawer}
+        ariaLabel="drawer component example"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          <Box>Drawer content&hellip;</Box>
+          <Box>Drawer content&hellip;</Box>
+          <Box>Drawer content&hellip;</Box>
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const Placement = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const [placement, setPlacement] = useState('right');
+  const placementOptions = [
+    {
+      id: 'top',
+      value: 'top',
+      label: 'top',
+    },
+    {
+      id: 'right',
+      value: 'right',
+      label: 'right',
+    },
+    {
+      id: 'bottom',
+      value: 'bottom',
+      label: 'bottom',
+    },
+    {
+      id: 'left',
+      value: 'left',
+      label: 'left',
+    },
+  ];
+  return (
+    <Box display="block" childGap="md">
+      <RadioGroup
+        title="Placement"
+        direction="row"
+        name="placement"
+        onChange={(event) => setPlacement(event.target.value)}
+        value={placement}
+        options={placementOptions}
+      />
+      <Button variant="primary" onClick={openDrawer}>
+        Open Drawer
+      </Button>
+      <Drawer
+        title="test"
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        placement={placement as DrawerPlacementType}
+        ariaLabel="drawer component example"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+          <Box as="p">drawer content</Box>
+        </Box>
+      </Drawer>
+    </Box>
+  );
+};
+
+export const DrawerHeader = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const drawerContent = [];
+  for (let i = 0; i < 50; i++) {
+    drawerContent.push(<Box key={i}>Drawer content&hellip;</Box>);
+  }
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Title and Close Button
+      </Button>
+      <Drawer
+        ariaLabel="drawer component example"
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        title="Drawer Title"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          {drawerContent}
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const TitleAndCloseButton = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const drawerContent = [];
+  for (let i = 0; i < 50; i++) {
+    drawerContent.push(<Box key={i}>Drawer content&hellip;</Box>);
+  }
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Title and Close Button
+      </Button>
+      <Drawer
+        ariaLabel="drawer component example"
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        title="Drawer Title"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          {drawerContent}
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const CloseButtonOnly = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const drawerContent = [];
+  for (let i = 0; i < 50; i++) {
+    drawerContent.push(<Box key={i}>Drawer content&hellip;</Box>);
+  }
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Close Button Only
+      </Button>
+      <Drawer
+        ariaLabel="drawer component example"
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        closeButton
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          {drawerContent}
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const Width = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const [width, setWidth] = React.useState('default');
+  const handleClick = (newWidth: WidthSize) => {
+    setWidth(newWidth);
+    openDrawer();
+  };
+  const widths = ['16rem', '400px', '100%'];
+  return (
+    <>
+      <Box gap="sm" direction="row">
+        {widths.map((width: string) => (
+          <Button
+            variant="primary"
+            onClick={() => handleClick(width as WidthSize)}
+            key={width}
+          >
+            {`Open ${width} Drawer `}
+          </Button>
+        ))}
+      </Box>
+      <Drawer
+        width={width as WidthSize}
+        title={`${width} wide drawer`}
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        closeButton
+        ariaLabel="drawer component example"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          <Box>drawer content</Box>
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const Height = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Open Drawer
+      </Button>
+      <Drawer
+        placement="top"
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        closeButton
+        ariaLabel="drawer component example"
+      >
+        <Box padding="lg" height="3xl" display="block" childGap="md">
+          <Box>3xl Height</Box>
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const HiddenOverlay = () => {
+  const closeBtnRef = useRef<HTMLButtonElement>();
+  const returnFocusRef = useRef<HTMLButtonElement>();
+  const returnFocus = () => {
+    if (returnFocusRef && returnFocusRef.current) {
+      returnFocusRef.current.focus();
+    }
+  };
+  const {
+    isOpen: isDrawerOpen,
+    handleToggle: handleDrawerToggle,
+    handleClose: closeDrawer,
+  } = useOpenClose({ onClose: returnFocus });
+  useEffect(() => {
+    setTimeout(() => {
+      if (closeBtnRef && closeBtnRef.current) {
+        closeBtnRef.current.focus();
+      }
+    }, 100);
+  }, [isDrawerOpen]);
+  return (
+    <>
+      <Button
+        variant="primary"
+        onClick={handleDrawerToggle}
+        ref={returnFocusRef as MutableRefObject<HTMLButtonElement>}
+      >
+        Toggle Drawer
+      </Button>
+      <Drawer
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        ariaLabel="drawer component example"
+        hideOverlay
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          <Button
+            ref={closeBtnRef as MutableRefObject<HTMLButtonElement>}
+            onClick={closeDrawer}
+            variant="primary"
+          >
+            close
+          </Button>
+          <Box>drawer content</Box>
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const InitialFocusRef = () => {
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  const ref = useRef(null);
+  return (
+    <>
+      <Button variant="primary" onClick={openDrawer}>
+        Open Drawer
+      </Button>
+      <Drawer
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        initialFocusRef={ref}
+        title="initialFocusRef"
+        ariaLabel="drawer component example"
+      >
+        <Box padding="2xl" display="block" childGap="md">
+          <Box>drawer content</Box>
+          <Button variant="primary" ref={ref} onClick={closeDrawer}>
+            I receive focus
+          </Button>
+        </Box>
+      </Drawer>
+    </>
+  );
+};
+
+export const ContainedDrawer = () => {
+  const containerRef = useRef<HTMLDivElement>();
+  const {
+    isOpen: isDrawerOpen,
+    handleOpen: openDrawer,
+    handleClose: closeDrawer,
+  } = useOpenClose();
+  return (
+    <Box
+      position="relative"
+      display="block"
+      height="500px"
+      id="myContainer"
+      ref={containerRef}
+      background="info"
+      padding="lg"
+      overflow="hidden"
+    >
+      <Button variant="primary" onClick={openDrawer}>
+        Show Drawer
+      </Button>
+      <Drawer
+        isOpen={isDrawerOpen}
+        onDismiss={closeDrawer}
+        containerRef={containerRef as MutableRefObject<HTMLDivElement>}
+        dangerouslyBypassScrollLock
+        hideOverlay
+        title="containerRef"
+        ariaLabel="drawer component example"
+      >
+        <Box padding="lg" as="p">
+          This drawer is rendered inside it&apos;s containing div, rather than
+          the document.body
+        </Box>
+      </Drawer>
+    </Box>
+  );
+};