@opentrons/components 0.1.6-alpha.8 → 0.1.7-alpha.0

package/src/tooltips/DeprecatedTooltip.tsx

@@ -0,0 +1,111 @@
+import { Manager, Reference, Popper } from 'react-popper'
+import cx from 'classnames'
+import styles from './tooltips.module.css'
+
+import type {
+  ComponentProps,
+  ComponentType,
+  PropsWithRef,
+  ReactNode,
+} from 'react'
+
+const DISTANCE_FROM_REFERENCE = 8
+
+type PopperProps = ComponentProps<typeof Popper>
+
+export interface DeprecatedTooltipProps {
+  /** show or hide the tooltip */
+  open?: boolean
+  /** contents of the tooltip */
+  tooltipComponent: ReactNode
+  /** optional portal to place the tooltipComponent inside */
+  portal?: ComponentType<any>
+  /** <https://github.com/FezVrasta/react-popper#placement> */
+  placement?: PopperProps['placement']
+  /** <https://github.com/FezVrasta/react-popper#positionfixed> */
+  positionFixed?: PopperProps['positionFixed']
+  /** <https://github.com/FezVrasta/react-popper#modifiers> */
+  modifiers?: PopperProps['modifiers']
+  /** render function for tooltip'd component */
+  children: (props?: PropsWithRef<any>) => JSX.Element | null
+  /** extra props to pass to the children render function */
+  childProps?: PropsWithRef<any>
+}
+
+/**
+ *  Basic, fully controlled Tooltip component.
+ *
+ * `props.children` is a function that receives the following props object:
+ * ```js
+ * type TooltipChildProps = {
+ *   ref: React.Ref<*>,
+ * }
+ * ```
+ *
+ * `props.childProps` can be used to add extra fields to the child props object
+ *
+ * @deprecated Use `Tooltip` and `useTooltip` instead
+ */
+export function DeprecatedTooltip(
+  props: DeprecatedTooltipProps
+): JSX.Element | null {
+  if (!props.tooltipComponent) return props.children()
+
+  return (
+    <Manager>
+      <Reference>
+        {
+          // TODO(mc, 2020-02-21): this is pretty hard to type as is, ref
+          // should probably be a whole separate argument to children
+          // this may become a moot point if we switch tooltips to hooks
+          ({ ref }) => props.children({ ...props.childProps, ref })
+        }
+      </Reference>
+      {props.open && (
+        <Popper
+          placement={props.placement}
+          modifiers={{
+            offset: { offset: `0, ${DISTANCE_FROM_REFERENCE}` },
+            ...props.modifiers,
+          }}
+          positionFixed={props.positionFixed}
+        >
+          {({ ref, style, placement, arrowProps }) => {
+            // remove optional -start and -end modifiers for arrow style
+            // https://popper.js.org/popper-documentation.html#Popper.placements
+            const arrowPlacement = placement
+              ? placement.replace(/-(?:start|end)/, '')
+              : ''
+
+            let { style: arrowStyle } = arrowProps
+            if (arrowPlacement === 'left' || arrowPlacement === 'right') {
+              arrowStyle = { top: '0.6em' }
+            }
+            const tooltipContents = (
+              <div
+                ref={ref}
+                className={styles.tooltip_box}
+                style={style}
+                data-placement={placement}
+              >
+                {props.tooltipComponent}
+                <div
+                  className={cx(styles.arrow, styles[arrowPlacement])}
+                  ref={arrowProps.ref}
+                  style={arrowStyle}
+                />
+              </div>
+            )
+
+            if (props.portal) {
+              const PortalClass = props.portal
+              return <PortalClass>{tooltipContents}</PortalClass>
+            }
+
+            return tooltipContents
+          }}
+        </Popper>
+      )}
+    </Manager>
+  )
+}

package/src/tooltips/HoverTooltip.tsx

@@ -0,0 +1,84 @@
+import { Component } from 'react'
+
+import { DeprecatedTooltip } from './DeprecatedTooltip'
+
+import type { PropsWithRef } from 'react'
+import type { DeprecatedTooltipProps } from './DeprecatedTooltip'
+
+const OPEN_DELAY_MS = 300
+const CLOSE_DELAY_MS = 0
+
+interface MouseHandlers {
+  onMouseEnter: () => void
+  onMouseLeave: () => void
+}
+
+export type HoverTooltipHandlers = PropsWithRef<MouseHandlers>
+
+export type HoverTooltipProps = DeprecatedTooltipProps
+
+interface HoverTooltipState {
+  isOpen: boolean
+}
+
+/**
+ * Tooltip component that triggers on `MouseEnter` and `MouseLeave`. See
+ * `Tooltip` for full props list.
+ *
+ * `props.children` is a function that receives the following props object:
+ * ```js
+ * type HoverTooltipHandlers = {
+ *   ref: React.Ref<*>,
+ *   onMouseEnter: (React.MouseEvent) => void,
+ *   onMouseLeave: (React.MouseEvent) => void,
+ * }
+ * ```
+ *
+ * @deprecated Use `Tooltip` and `useHoverTooltip` instead
+ */
+export class HoverTooltip extends Component<
+  HoverTooltipProps,
+  HoverTooltipState
+> {
+  openTimeout: number | null
+  closeTimeout: number | null
+
+  constructor(props: HoverTooltipProps) {
+    super(props)
+    this.openTimeout = null
+    this.closeTimeout = null
+    this.state = { isOpen: false }
+  }
+
+  componentWillUnmount(): void {
+    if (this.closeTimeout) clearTimeout(this.closeTimeout)
+    if (this.openTimeout) clearTimeout(this.openTimeout)
+  }
+
+  delayedOpen: () => void = () => {
+    if (this.closeTimeout) clearTimeout(this.closeTimeout)
+    this.openTimeout = window.setTimeout(() => {
+      this.setState({ isOpen: true })
+    }, OPEN_DELAY_MS)
+  }
+
+  delayedClose: () => void = () => {
+    if (this.openTimeout) clearTimeout(this.openTimeout)
+    this.closeTimeout = window.setTimeout(() => {
+      this.setState({ isOpen: false })
+    }, CLOSE_DELAY_MS)
+  }
+
+  render(): JSX.Element {
+    return (
+      <DeprecatedTooltip
+        open={this.state.isOpen}
+        childProps={{
+          onMouseEnter: this.delayedOpen,
+          onMouseLeave: this.delayedClose,
+        }}
+        {...this.props}
+      />
+    )
+  }
+}

package/src/tooltips/LegacyTooltip.stories.tsx

@@ -0,0 +1,98 @@
+import type * as React from 'react'
+import { LegacyTooltip } from './LegacyTooltip'
+import { useTooltip } from './useTooltip'
+import { useHoverTooltip } from './useHoverTooltip'
+import {
+  Box,
+  Flex,
+  JUSTIFY_CENTER,
+  ALIGN_CENTER,
+  SIZE_4,
+  SIZE_3,
+  C_LIGHT_GRAY,
+  C_MED_GRAY,
+} from '@opentrons/components'
+
+import type { Story, Meta } from '@storybook/react'
+
+export default {
+  title: 'Library/Atoms/LegacyTooltip',
+  decorators: [
+    Story => (
+      <Flex
+        justifyContent={JUSTIFY_CENTER}
+        alignItems={ALIGN_CENTER}
+        height={SIZE_4}
+        width="100%"
+        backgroundColor={C_LIGHT_GRAY}
+      >
+        <Story />
+      </Flex>
+    ),
+  ],
+} as Meta
+
+const Template: Story<React.ComponentProps<typeof LegacyTooltip>> = args => (
+  <LegacyTooltip {...args} />
+)
+export const Basic = Template.bind({})
+Basic.args = {
+  visible: true,
+  children: 'This is a simple tooltip atom.',
+  id: 'string-usually-provided-by-useTooltip-hook',
+  placement: 'auto',
+  style: {},
+  arrowRef: () => null,
+  arrowStyle: {},
+}
+
+const StatefulTemplate: Story<
+  React.ComponentProps<typeof LegacyTooltip>
+> = args => {
+  const { visible, children, placement } = args
+  const [targetProps, tooltipProps] = useTooltip({ placement })
+  return (
+    <>
+      <Box
+        height={SIZE_3}
+        width={SIZE_3}
+        backgroundColor={C_MED_GRAY}
+        {...targetProps}
+      >
+        Target
+      </Box>
+      <LegacyTooltip {...tooltipProps} {...{ visible, children }} />
+    </>
+  )
+}
+export const WithUseTooltip = StatefulTemplate.bind({})
+WithUseTooltip.args = {
+  visible: true,
+  children:
+    'This is a tooltip that takes advantage of the useTooltip hook to anchor itself to a target.',
+}
+
+const HoverTemplate: Story<
+  React.ComponentProps<typeof LegacyTooltip>
+> = args => {
+  const { children } = args
+  const [targetProps, tooltipProps] = useHoverTooltip()
+  return (
+    <>
+      <Box
+        height={SIZE_3}
+        width={SIZE_3}
+        backgroundColor={C_MED_GRAY}
+        {...targetProps}
+      >
+        Target
+      </Box>
+      <LegacyTooltip {...tooltipProps}>{children}</LegacyTooltip>
+    </>
+  )
+}
+export const WithUseHoverTooltip = HoverTemplate.bind({})
+WithUseHoverTooltip.args = {
+  children:
+    'This is a tooltip that takes advantage of the useHoverTooltip hook, and only appears when the target is hovered.',
+}

package/src/tooltips/LegacyTooltip.tsx

@@ -0,0 +1,151 @@
+import { forwardRef } from 'react'
+import { css } from 'styled-components'
+
+import { BORDERS, COLORS } from '../helix-design-system'
+import { fontSizeH4 } from '../ui-style-constants/typography'
+import { spacing8 } from '../ui-style-constants/spacing'
+import { ARROW_SIZE_PX } from './styles'
+import { Box } from '../primitives'
+import { CURSOR_POINTER } from '../styles'
+
+import type { CSSProperties, ForwardedRef, ReactNode, RefCallback } from 'react'
+import type { FlattenSimpleInterpolation } from 'styled-components'
+import type { Placement } from './types'
+import type { StyleProps } from '../primitives'
+
+export interface LegacyTooltipProps extends StyleProps {
+  /** Whether or not the tooltip should be rendered */
+  visible: boolean
+  /** Contents of the tooltip */
+  children?: ReactNode
+  /**
+   * Tooltip element ID (provided by useTooltip). Will match
+   * targetProps.aria-describedby
+   */
+  id: string
+  /** Actual tooltip placement, if known (provided by useTooltip) */
+  placement: Placement | null
+  /** Inline styles to apply to the tooltip element (provided by useTooltip) */
+  style: CSSProperties
+  /** React function ref for tooltip's arrow element (provided by useTooltip) */
+  arrowRef: RefCallback<HTMLElement | null>
+  /** Inline styles to apply to arrow element (provided by useTooltip) */
+  arrowStyle: CSSProperties
+}
+
+/**
+ * Tooltip component that renders based on its `visible` prop. For use with the
+ * `useTooltip` and `useHoverTooltip` hooks. See examples in `Tooltip.md`.
+ */
+export const LegacyTooltip = forwardRef(function TooltipComponent(
+  props: LegacyTooltipProps,
+  ref: ForwardedRef<HTMLDivElement>
+) {
+  const {
+    visible,
+    placement,
+    id,
+    style,
+    arrowRef,
+    arrowStyle,
+    children,
+    width,
+    fontSize = fontSizeH4,
+    backgroundColor = COLORS.grey50,
+    ...boxProps
+  } = props
+
+  const TOOLTIP_CSS = css`
+    position: absolute;
+    z-index: 9001;
+    padding: ${spacing8};
+    color: ${COLORS.white};
+    filter: drop-shadow(0px 1px 3px rgba(0, 0, 0, 0.2));
+    cursor: ${CURSOR_POINTER};
+    font-size: ${fontSize};
+    border-radius: ${BORDERS.borderRadius4};
+  `
+
+  return visible ? (
+    <Box
+      role="tooltip"
+      id={id}
+      style={style}
+      ref={ref}
+      css={TOOLTIP_CSS}
+      width={width}
+      backgroundColor={backgroundColor}
+      {...boxProps}
+    >
+      {children}
+      <Arrow {...{ arrowRef, arrowStyle, placement, backgroundColor }} />
+    </Box>
+  ) : null
+})
+
+export interface ArrowProps {
+  placement: Placement | null
+  arrowRef: RefCallback<HTMLElement>
+  arrowStyle: CSSProperties
+  backgroundColor: string
+}
+
+export function Arrow(props: ArrowProps): JSX.Element {
+  // shift arrows off the element
+  const ARROW_ANCHOR_OFFSET = `-${ARROW_SIZE_PX}px;`
+
+  // use borders to create arrows
+  const ARROW_CSS_BASE = css`
+    position: absolute;
+    border-width: ${ARROW_SIZE_PX}px;
+    border-style: solid;
+    border-color: transparent;
+  `
+
+  // arrow pointing down from the top tooltip
+  const ARROW_CSS_TOP = css`
+    ${ARROW_CSS_BASE}
+    bottom: ${ARROW_ANCHOR_OFFSET};
+    border-bottom-style: none;
+    border-top-color: ${props.backgroundColor};
+  `
+
+  // arrow pointing left from the right tooltip
+  const ARROW_CSS_RIGHT = css`
+    ${ARROW_CSS_BASE}
+    left: ${ARROW_ANCHOR_OFFSET};
+    border-left-style: none;
+    border-right-color: ${props.backgroundColor};
+  `
+
+  // arrow pointing up from the bottom tooltip
+  const ARROW_CSS_BOTTOM = css`
+    ${ARROW_CSS_BASE}
+    top: ${ARROW_ANCHOR_OFFSET};
+    border-top-style: none;
+    border-bottom-color: ${props.backgroundColor};
+  `
+
+  // arrow pointing right from the left tooltip
+  const ARROW_CSS_LEFT = css`
+    ${ARROW_CSS_BASE}
+    right: ${ARROW_ANCHOR_OFFSET};
+    border-right-style: none;
+    border-left-color: ${props.backgroundColor};
+  `
+
+  const ARROW_CSS_BY_PLACEMENT_BASE: Record<
+    string,
+    FlattenSimpleInterpolation
+  > = {
+    top: ARROW_CSS_TOP,
+    right: ARROW_CSS_RIGHT,
+    bottom: ARROW_CSS_BOTTOM,
+    left: ARROW_CSS_LEFT,
+  }
+  const placement = props.placement ?? ''
+  const placementBase = placement.split('-')[0]
+  const arrowCss = ARROW_CSS_BY_PLACEMENT_BASE[placementBase]
+
+  return <div ref={props.arrowRef} style={props.arrowStyle} css={arrowCss} />
+}

package/src/tooltips/__tests__/Tooltip.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('hook-based Tooltip', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/tooltips/__tests__/useHoverTooltip.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('useHoverTooltip', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/tooltips/__tests__/usePopper.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('usePopper hook', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/tooltips/__tests__/useTooltip.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('useTooltip hook', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/tooltips/constants.ts

@@ -0,0 +1,28 @@
+// placement constants
+// NOTE: these aren't exported from Popper, but they are copied from:
+// @popperjs/core/src/enums.js
+export const TOOLTIP_AUTO: 'auto' = 'auto'
+export const TOOLTIP_AUTO_START: 'auto-start' = 'auto-start'
+export const TOOLTIP_AUTO_END: 'auto-end' = 'auto-end'
+
+export const TOOLTIP_TOP: 'top' = 'top'
+export const TOOLTIP_TOP_START: 'top-start' = 'top-start'
+export const TOOLTIP_TOP_END: 'top-end' = 'top-end'
+
+export const TOOLTIP_RIGHT: 'right' = 'right'
+export const TOOLTIP_RIGHT_START: 'right-start' = 'right-start'
+export const TOOLTIP_RIGHT_END: 'right-end' = 'right-end'
+
+export const TOOLTIP_BOTTOM: 'bottom' = 'bottom'
+export const TOOLTIP_BOTTOM_START: 'bottom-start' = 'bottom-start'
+export const TOOLTIP_BOTTOM_END: 'bottom-end' = 'bottom-end'
+
+export const TOOLTIP_LEFT: 'left' = 'left'
+export const TOOLTIP_LEFT_START: 'left-start' = 'left-start'
+export const TOOLTIP_LEFT_END: 'left-end' = 'left-end'
+
+// strategy constants
+// NOTE: these aren't exported from Popper, but they are copied from:
+// @popperjs/core/src/types.js
+export const TOOLTIP_ABSOLUTE: 'absolute' = 'absolute'
+export const TOOLTIP_FIXED: 'fixed' = 'fixed'

package/src/tooltips/index.ts

@@ -0,0 +1,10 @@
+// tooltip components
+
+export * from './DeprecatedTooltip'
+export * from './HoverTooltip'
+export * from './LegacyTooltip'
+export * from './useTooltip'
+export * from './useHoverTooltip'
+export * from './usePopper'
+export * from './constants'
+export * from './types'

package/src/tooltips/styles.ts

@@ -0,0 +1,20 @@
+// common style constants
+
+export const INITIAL_TOOLTIP_STYLE = {
+  // copied from @popperjs/core/src/modifiers/applyStyles.js
+  position: 'absolute',
+  left: '0',
+  top: '0',
+  margin: '0',
+} as const
+
+export const INITIAL_ARROW_STYLE = {
+  // copied from @popperjs/core/src/modifiers/applyStyles.js
+  position: 'absolute',
+} as const
+
+export const TOOLTIP_OFFSET_PX = 8
+
+export const ARROW_OFFSET_PX = 4
+
+export const ARROW_SIZE_PX = TOOLTIP_OFFSET_PX - ARROW_OFFSET_PX

package/src/tooltips/tooltips.module.css

@@ -0,0 +1,72 @@
+/* common styling for tooltips */
+@import '../index.module.css';
+
+.tooltip_box {
+  font-size: var(--fs-body-1); /* from legacy --font-body-1-light */
+  font-weight: var(--fw-regular); /* from legacy --font-body-1-light */
+  color: var(--c-font-light); /* from legacy --font-body-1-light */
+  background-color: var(--c-bg-dark);
+  box-shadow: 0 3px 6px 0 rgba(0, 0, 0, 0.13), 0 3px 6px 0 rgba(0, 0, 0, 0.23);
+  padding: 8px;
+  cursor: pointer;
+  z-index: 9001;
+}
+
+.arrow {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  margin-bottom: -0.5em;
+  width: 1em;
+  height: 0.5em;
+
+  &::before {
+    border-width: 0.5em 0.5em 0 0.5em;
+    content: '';
+    margin: auto;
+    display: block;
+    width: 0;
+    height: 0;
+    border-style: solid;
+    border-color: var(--c-bg-dark) transparent transparent transparent;
+  }
+}
+
+.arrow.bottom {
+  top: 0;
+  left: 0;
+  margin-top: -0.5em;
+  width: 1em;
+  height: 0.5em;
+
+  &::before {
+    border-width: 0 0.5em 0.5em 0.5em;
+    border-color: transparent transparent var(--c-bg-dark) transparent;
+  }
+}
+
+.arrow.right {
+  top: 0;
+  left: 0;
+  margin-left: -0.5em;
+  height: 1em;
+  width: 0.5em;
+
+  &::before {
+    border-width: 0.5em 0.5em 0.5em 0;
+    border-color: transparent var(--c-bg-dark) transparent transparent;
+  }
+}
+
+.arrow.left {
+  top: 0;
+  right: 0;
+  margin-right: -0.5em;
+  height: 1em;
+  width: 0.5em;
+
+  &::before {
+    border-width: 0.5em 0 0.5em 0.5em;
+    border-color: transparent transparent transparent var(--c-bg-dark);
+  }
+}

package/src/tooltips/types.ts

@@ -0,0 +1,73 @@
+import type { CSSProperties, RefCallback } from 'react'
+
+import type { Instance, Options, Modifier } from '@popperjs/core/lib/types'
+
+import type { UseHoverOptions, HoverHandlers } from '../interaction-enhancers'
+
+export type Placement = Options['placement']
+
+export type Strategy = Options['strategy']
+
+export type PopperInstance = Instance
+
+export type PopperOptions = Options
+
+export type PopperModifer<T> = Modifier<T>
+
+export type HandleStateUpdate = (
+  placement: Placement,
+  styles: {
+    popper?: CSSProperties
+    arrow?: CSSProperties
+  }
+) => void
+
+export interface UsePopperOptions {
+  target: Element | null
+  tooltip: HTMLElement | null
+  arrow: HTMLElement | null
+  onStateUpdate: HandleStateUpdate
+  placement?: Placement | null
+  strategy?: Strategy | null
+  offset?: number
+}
+
+export type UsePopperResult = Instance | null
+
+export interface UseTooltipOptions {
+  placement?: Placement
+  strategy?: Strategy
+  offset?: number
+}
+
+export interface UseTooltipResultTargetProps {
+  ref: RefCallback<Element | null>
+  'aria-describedby': string
+}
+
+export interface UseTooltipResultTooltipProps {
+  id: string
+  ref: RefCallback<HTMLElement | null>
+  placement: Placement | null
+  style: CSSProperties
+  arrowRef: RefCallback<HTMLElement | null>
+  arrowStyle: CSSProperties
+}
+
+export type UseTooltipResult = [
+  UseTooltipResultTargetProps,
+  UseTooltipResultTooltipProps
+]
+
+export type UseHoverTooltipOptions = Partial<
+  UseTooltipOptions & UseHoverOptions
+>
+
+export interface UseHoverTooltipTargetProps
+  extends UseTooltipResultTargetProps,
+    HoverHandlers {}
+
+export type UseHoverTooltipResult = [
+  UseHoverTooltipTargetProps,
+  UseTooltipResultTooltipProps & { visible: boolean }
+]