@hyphen/hyphen-components 2.9.0

package/src/components/Popover/Popover.mdx

@@ -0,0 +1,104 @@
+import { Canvas, Meta, ArgTypes } from '@storybook/blocks';
+import { Popover } from './Popover';
+import * as Stories from './Popover.stories';
+
+<Meta of={Stories} />
+
+# Popover
+
+Use popovers to show content of any kind behind the context of a specific trigger, some examples
+of uses for a popover include:
+
+1. Dropdowns
+2. Tooltips
+3. Context Menus
+
+<Canvas withSource="open" of={Stories.BasicUsage} />
+
+The popover requires a `children` node that will act as a trigger, as well as a `content` prop that has the contents of the Popover.
+
+Use the `isOpen` prop to govern the state of the Popover. This is done by attaching a `onClick` event to the trigger element.
+
+By default the Popover will render with placement on the right, as well as a white background and some base padding on the container. All of these
+items, however are fully customizable.
+
+## Props
+
+<ArgTypes of={Popover} />
+
+## Popover Styling
+
+Because the rendered Popover is powered by our `Box` component ([Read More](/?path=/docs/components-box-overview--background)) you
+can use all known box props to style it. The below example includes some of the basics, but is not representative of
+the entire gamut of styling options.
+
+<Canvas withSource="open" of={Stories.PopoverStyling} />
+
+## Placement
+
+Based on layout, it is beneficial to place the popover in a variety of positions relative to its trigger element.
+Note that in case where the popover is in danger of overflowing, the component will fallback to `auto` in order to
+prevent the content from getting cut off.
+
+<Canvas withSource="open" of={Stories.Placement} />
+
+## With a Portal
+
+Popovers in lots of cases need to break away from the HTML structure of their parent elements
+in order to maintain semantic order on the page. This can also help with z-index conflicts
+and ensure content isn't cut off in certain cases by the popover's parent container.
+
+To render the Popover outside in an element other than its parent container, we
+use a (React Portal)[https://reactjs.org/docs/portals.html].
+
+By default the element is portaled into the document `body` but you can use the `portalTarget` prop
+in order to render the element anywhere on the page.
+
+<Canvas withSource="open" of={Stories.WithAPortal} />
+
+## Hover Trigger
+
+In cases where small amounts of additional context are needed for a particular item,
+it might be beneficial to trigger the Popover on hover. Since the component is fully controlled
+this can be done easily by attaching mouse events to the trigger element as show below.
+
+NOTE: this should be use sparingly since context dependent on hover, isn't an optimal experience for mobile users.
+
+<Canvas withSource="open" of={Stories.HoverTrigger} />
+
+## Respond to Outside Clicks
+
+Since Popovers are by nature rendered on top of existing content, it
+is beneficial in most cases to close the Popover when a user clicks any item outside
+the trigger and popover content.
+
+Our component provides a `onClickOutside` prop that fires a callback whenever there is a click
+event outside the Popover content, OR, when the user taps the `Escape` key.
+You can use the callback to set `isOpen` to false.
+
+NOTE: the click event is attached to the `document.body`, but will not bubble up the event
+in cases where the click target includes the Popover trigger or content nodes.
+
+<Canvas withSource="open" of={Stories.RespondToOutsideClicks} />
+
+## Trapping Focus
+
+Trapping focus in a Popover is valuable in many cases to preserve accessibility. It consists
+of constraining the items available for focusing to ONLY the content of the Popover, hence preventing
+users from focusing on elements that might be behind or outside the Popover content.
+
+Use the `trapFocus` prop to constrain focus to popover content elements.
+
+<Canvas withSource="open" of={Stories.TrappingFocus} />
+
+## Without An Arrow
+
+Render the popover with no arrow by passing `hasArrow` false.
+
+<Canvas withSource="open" of={Stories.WithoutAnArrow} />
+
+## Offset Distance
+
+Place the popover closer or farther from its trigger with the `offsetFromTarget` prop.
+
+<Canvas withSource="open" of={Stories.OffsetDistance} />

package/src/components/Popover/Popover.module.scss

@@ -0,0 +1,74 @@
+@keyframes fadeIn {
+  0% {
+    opacity: 0;
+  }
+
+  100% {
+    opacity: 1;
+  }
+}
+
+.popover {
+  z-index: var(--size-z-index-popover);
+  animation: fadeIn 0.2s;
+}
+
+.popover-arrow {
+  position: absolute;
+  width: 0.8rem;
+  height: 0.8rem;
+
+  &::before {
+    position: absolute;
+    transform: rotate(45deg);
+    z-index: -1;
+    background-color: inherit;
+    width: 0.8rem;
+    height: 0.8rem;
+    content: '';
+  }
+}
+
+[data-popper-placement*='bottom'] {
+  .popover-arrow {
+    top: -0.1rem;
+
+    &::before {
+      bottom: 0.25rem;
+      box-shadow: rgb(0 0 0 / 5%) -1px -1px 1px 0;
+    }
+  }
+}
+
+[data-popper-placement*='top'] {
+  .popover-arrow {
+    bottom: -0.1rem;
+
+    &::before {
+      top: 0.25rem;
+      box-shadow: rgb(0 0 0 / 8%) 3px 3px 3px 0;
+    }
+  }
+}
+
+[data-popper-placement*='left'] {
+  .popover-arrow {
+    right: -0.1rem;
+
+    &::before {
+      left: 0.25rem;
+      box-shadow: rgb(0 0 0 / 8%) 1px -1px 1px 0;
+    }
+  }
+}
+
+[data-popper-placement*='right'] {
+  .popover-arrow {
+    left: -0.1rem;
+
+    &::before {
+      right: 0.25rem;
+      box-shadow: rgb(0 0 0 / 5%) -2px 2px 2px 0;
+    }
+  }
+}

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

@@ -0,0 +1,471 @@
+import { Popover } from './Popover';
+import type { Meta } from '@storybook/react';
+import React, { ChangeEvent } from 'react';
+import { useState } from 'react';
+import { Button } from '../Button/Button';
+import { Box } from '../Box/Box';
+import { SelectInput } from '../SelectInput/SelectInput';
+import { TextInput } from '../TextInput/TextInput';
+import { Heading } from '../Heading/Heading';
+import { useOpenClose } from '../../hooks/useOpenClose/useOpenClose';
+import {
+  BackgroundColor,
+  FontColor,
+} from '@hyphen/hyphen-design-tokens/build/types';
+
+const meta: Meta<typeof Popover> = {
+  title: 'Components/Popover',
+  component: Popover,
+};
+
+export default meta;
+
+export const BasicUsage = () => {
+  const {
+    isOpen: isPopoverOpen,
+    handleToggle: togglePopover,
+    handleClose: closePopover,
+  } = useOpenClose();
+  const popoverContent = <>Hello!</>;
+  return (
+    <>
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right"
+        contentContainerProps={{
+          padding: 'sm',
+        }}
+        onClickOutside={closePopover}
+      >
+        <Button onClick={togglePopover} variant="primary">
+          Toggle Popover
+        </Button>
+      </Popover>
+    </>
+  );
+};
+
+type PopoverStylingType = {
+  value: string;
+  label: string;
+} | null;
+
+export const PopoverStyling = () => {
+  const { isOpen: isPopoverOpen, handleToggle: togglePopover } = useOpenClose();
+  const [popoverBackground, setPopoverBackground] =
+    useState<PopoverStylingType>({
+      value: 'primary-500',
+      label: 'Primary 500',
+    });
+  const [popoverFontColor, setPopoverFontColor] = useState<PopoverStylingType>({
+    value: 'black-500',
+    label: 'Black 500',
+  });
+  const [popoverRadius, setPopoverRadius] = useState<PopoverStylingType>({
+    value: 'sm',
+    label: 'Small',
+  });
+  const backgroundOptions = [
+    { value: 'primary', label: 'primary' },
+    { value: 'secondary', label: 'secondary' },
+    { value: 'info', label: 'info' },
+    { value: 'warning', label: 'warn' },
+    { value: 'danger', label: 'danger' },
+  ];
+  const fontColorOptions = [
+    { value: 'base', label: 'base' },
+    { value: 'inverse', label: 'inverse' },
+  ];
+  const borderRadiusOptions = [
+    { value: 'sm', label: 'Small' },
+    { value: 'md', label: 'Medium' },
+    { value: 'lg', label: 'Large' },
+  ];
+  return (
+    <Box height="400px">
+      <Box direction="row" gap="md" wrap>
+        <Popover
+          content={
+            <>
+              <p>Hello world!</p>
+              <p>Style me any way you want</p>
+            </>
+          }
+          isOpen={isPopoverOpen}
+          placement={'right'}
+          contentContainerProps={{
+            padding: 'sm',
+            background: popoverBackground!.value as BackgroundColor,
+            color: popoverFontColor!.value as FontColor,
+            radius: popoverRadius!.value,
+          }}
+        >
+          <Button onClick={togglePopover} variant="primary">
+            Toggle Popover
+          </Button>
+        </Popover>
+      </Box>
+      <Box direction="row" gap="sm" wrap margin="3xl 0 0 0">
+        <Box width="200px">
+          <SelectInput
+            id="backgroundOptions"
+            options={backgroundOptions}
+            onChange={(event) => {
+              // @ts-ignore
+              setPopoverBackground(event.target.value);
+            }}
+            value={popoverBackground}
+            label="Background Color"
+          />
+        </Box>
+        <Box width="200px">
+          <SelectInput
+            id="fontColorOptions"
+            options={fontColorOptions}
+            onChange={(event) => {
+              // @ts-ignore
+              setPopoverFontColor(event.target.value);
+            }}
+            value={popoverFontColor}
+            label="Font Color"
+          />
+        </Box>
+        <Box width="200px">
+          <SelectInput
+            id="borderRadiusOptions"
+            options={borderRadiusOptions}
+            onChange={(event) => {
+              // @ts-ignore
+              setPopoverRadius(event.target.value);
+            }}
+            value={popoverRadius}
+            label="Border Radius"
+          />
+        </Box>
+      </Box>
+    </Box>
+  );
+};
+
+export const Placement = () => {
+  const [isPopoverOpen, setPopoverOpen] = useState({
+    auto: false,
+    'auto-start': false,
+    'auto-end': false,
+    top: false,
+    bottom: false,
+    right: false,
+    left: false,
+    'top-start': false,
+    'top-end': false,
+    'bottom-start': false,
+    'bottom-end': false,
+    'right-start': false,
+    'right-end': false,
+    'left-start': false,
+    'left-end': false,
+  });
+  const handleOpenPopover = (key: string) => {
+    // @ts-ignore
+    setPopoverOpen({ ...isPopoverOpen, [key]: !isPopoverOpen[key] });
+  };
+  const positions = [
+    'auto',
+    'auto-start',
+    'auto-end',
+    'top',
+    'bottom',
+    'right',
+    'left',
+    'top-start',
+    'top-end',
+    'bottom-start',
+    'bottom-end',
+    'right-start',
+    'right-end',
+    'left-start',
+    'left-end',
+  ];
+
+  return (
+    <Box direction="row" gap="md" wrap>
+      {positions.map((position) => (
+        <Box height="100px" padding="5xl" display="inline-block" key={position}>
+          <Popover
+            content={<>{position}</>}
+            // @ts-ignore
+            isOpen={isPopoverOpen[position]}
+            // @ts-ignore
+            placement={position}
+            contentContainerProps={{
+              padding: 'sm',
+              background: 'info',
+              color: 'base',
+            }}
+          >
+            <Button
+              onClick={() => handleOpenPopover(position)}
+              variant="primary"
+            >
+              {position}
+            </Button>
+          </Popover>
+        </Box>
+      ))}
+    </Box>
+  );
+};
+
+export const WithAPortal = () => {
+  const {
+    isOpen: isPopoverOpen,
+    handleToggle: togglePopover,
+    handleClose: closePopover,
+  } = useOpenClose();
+  const popoverContent = (
+    <>
+      <Heading style={{ marginBottom: '0.5rem' }}>
+        I am living in the body element!
+      </Heading>
+      <p>That's why I can break out of my container without getting cut off</p>
+    </>
+  );
+  return (
+    <Box display="inline-block">
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right-start"
+        contentContainerProps={{
+          padding: 'md',
+          background: 'danger',
+          color: 'base',
+        }}
+        withPortal
+        portalTarget={document.body}
+        onClickOutside={closePopover}
+      >
+        <Button onClick={togglePopover} variant="primary">
+          Toggle Popover
+        </Button>
+      </Popover>
+    </Box>
+  );
+};
+
+export const HoverTrigger = () => {
+  const {
+    isOpen: isPopoverOpen,
+    handleClose: closePopover,
+    handleOpen: openPopover,
+  } = useOpenClose();
+  const popoverContent = (
+    <>
+      <Heading style={{ marginBottom: '0.5rem' }}>
+        I just appeared on hover!
+      </Heading>
+      <p>
+        My visibility can easily be managed by attaching listeners to the
+        trigger element
+      </p>
+    </>
+  );
+  return (
+    <Box display="inline-block">
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right-start"
+        contentContainerProps={{
+          padding: 'md',
+          background: 'info',
+        }}
+      >
+        <Button
+          onMouseOver={openPopover}
+          onMouseOut={closePopover}
+          variant="primary"
+        >
+          Hover Me
+        </Button>
+      </Popover>
+    </Box>
+  );
+};
+
+export const RespondToOutsideClicks = () => {
+  const {
+    isOpen: isPopoverOpen,
+    handleClose: closePopover,
+    handleToggle: togglePopover,
+  } = useOpenClose();
+  const popoverContent = (
+    <>
+      <Heading style={{ marginBottom: '0.5rem' }}>
+        I will close if you click outside!
+      </Heading>
+      <p>The event listener is attached to the document body.</p>
+    </>
+  );
+  return (
+    <Box display="inline-block">
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right-start"
+        withPortal
+        portalTarget={document.body}
+        onClickOutside={closePopover}
+        contentContainerProps={{
+          padding: 'md',
+          background: 'success',
+        }}
+      >
+        <Button onClick={togglePopover} variant="primary">
+          Toggle Popover
+        </Button>
+      </Popover>
+    </Box>
+  );
+};
+
+export const TrappingFocus = () => {
+  const [inputValue, setInputValue] = useState<string>('');
+  const {
+    isOpen: isPopoverOpen,
+    handleClose: closePopover,
+    handleToggle: togglePopover,
+  } = useOpenClose();
+  const handleInputChange = (event: ChangeEvent<HTMLInputElement>) => {
+    setInputValue(event.target.value);
+  };
+  const popoverContent = (
+    <>
+      <Box direction="column" gap="sm">
+        <Heading>Only the elements on this Popover can be tabbed into</Heading>
+        <TextInput
+          id="textInput"
+          label="Text Input"
+          onChange={handleInputChange}
+          value={inputValue}
+        />
+        <Button>Submit</Button>
+      </Box>
+    </>
+  );
+  return (
+    <Box display="inline-block">
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right-start"
+        contentContainerProps={{
+          padding: 'md',
+          background: 'primary',
+        }}
+        withPortal
+        portalTarget={document.body}
+        onClickOutside={closePopover}
+        trapFocus
+      >
+        <Button onClick={togglePopover} variant="primary">
+          Toggle Popover
+        </Button>
+      </Popover>
+    </Box>
+  );
+};
+
+export const WithoutAnArrow = () => {
+  const {
+    isOpen: isPopoverOpen,
+    handleToggle: togglePopover,
+    handleClose: closePopover,
+  } = useOpenClose();
+  const popoverContent = (
+    <>
+      <Box direction="column" gap="sm">
+        <Heading>With no arrow</Heading>
+        <p>I am floating in space</p>
+      </Box>
+    </>
+  );
+  return (
+    <>
+      <Popover
+        content={popoverContent}
+        isOpen={isPopoverOpen}
+        placement="right"
+        contentContainerProps={{
+          padding: 'sm',
+        }}
+        onClickOutside={closePopover}
+        hasArrow={false}
+      >
+        <Button onClick={togglePopover} variant="primary">
+          Toggle Popover
+        </Button>
+      </Popover>
+    </>
+  );
+};
+
+export const OffsetDistance = () => {
+  const [offset, setOffset] = useState<number>(12);
+  const { isOpen: isPopoverOpen, handleToggle: togglePopover } = useOpenClose();
+
+  const popoverContent = (
+    <>
+      <Box direction="column" gap="sm">
+        <Heading>Custom Offset</Heading>
+        <p>Near, far, wherever your are...</p>
+      </Box>
+    </>
+  );
+  return (
+    <>
+      <Box display="inline-block">
+        <Popover
+          content={popoverContent}
+          isOpen={isPopoverOpen}
+          placement="right-start"
+          contentContainerProps={{
+            padding: 'md',
+            background: 'secondary',
+          }}
+          withPortal
+          portalTarget={document.body}
+          hasArrow={false}
+          offsetFromTarget={offset}
+        >
+          <Button onClick={togglePopover} variant="primary">
+            Toggle Popover
+          </Button>
+        </Popover>
+      </Box>
+      <Box margin="2xl 0 0 0" maxWidth="300px">
+        <label
+          htmlFor="offset"
+          style={{ fontWeight: 'bold', marginBottom: '0.25rem' }}
+        >
+          Offset
+        </label>
+        <input
+          type="range"
+          id="offset"
+          name="offset"
+          min="0"
+          max="24"
+          step="1"
+          value={offset}
+          onChange={(event) => {
+            setOffset(event.target.value as unknown as number);
+          }}
+          style={{ marginBottom: '0.25rem' }}
+        />
+        <span style={{ display: 'inline' }}>Value: {offset}</span>
+      </Box>
+    </>
+  );
+};