@opentrons/components 0.1.6-alpha.2 → 0.1.6-alpha.21

package/src/tooltips/HoverTooltip.tsx

@@ -0,0 +1,83 @@
+import * as React from 'react'
+
+import { DeprecatedTooltip } from './DeprecatedTooltip'
+
+import type { DeprecatedTooltipProps } from './DeprecatedTooltip'
+
+const OPEN_DELAY_MS = 300
+const CLOSE_DELAY_MS = 0
+
+interface MouseHandlers {
+  onMouseEnter: () => void
+  onMouseLeave: () => void
+}
+
+export type HoverTooltipHandlers = React.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 React.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 * as React 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 } 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?: React.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: React.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 = React.forwardRef(function TooltipComponent(
+  props: LegacyTooltipProps,
+  ref: React.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: React.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/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/types.ts

@@ -0,0 +1,73 @@
+import type { CSSProperties } 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: React.RefCallback<Element | null>
+  'aria-describedby': string
+}
+
+export interface UseTooltipResultTooltipProps {
+  id: string
+  ref: React.RefCallback<HTMLElement | null>
+  placement: Placement | null
+  style: CSSProperties
+  arrowRef: React.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 }
+]

package/src/tooltips/useHoverTooltip.ts

@@ -0,0 +1,47 @@
+import { useHover } from '../interaction-enhancers'
+import { useTooltip } from './useTooltip'
+
+import type { UseHoverTooltipOptions, UseHoverTooltipResult } from './types'
+
+const ENTER_DELAY_MS = 300
+const LEAVE_DELAY_MS = 0
+
+/**
+ * Hook to position a tooltip component relative to a target component on hover.
+ * Adds a default `enterDelay` of 300 ms before the tooltip will show
+ *
+ * @param {UseHoverTooltipOptions} [options={}] (change default options (see `useTooltip` and `useHover`))
+ * @returns {UseHoverTooltipResult}
+ * @example
+ * ```js
+ * import { useHoverTooltip, Tooltip } from '@opentrons/components'
+ *
+ * export function HelloWorld() {
+ *   const [targetProps, tooltipProps] = useHoverTooltip()
+ *
+ *   return (
+ *     <>
+ *       <span {...targetProps}>Hello</span>
+ *       <Tooltip {...tooltipProps}>World</Tooltip>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function useHoverTooltip(
+  options: UseHoverTooltipOptions = {}
+): UseHoverTooltipResult {
+  const {
+    enterDelay = ENTER_DELAY_MS,
+    leaveDelay = LEAVE_DELAY_MS,
+    ...useTooltipOptions
+  } = options
+
+  const [targetProps, tooltipProps] = useTooltip(useTooltipOptions)
+  const [visible, hoverHandlers] = useHover({ enterDelay, leaveDelay })
+
+  return [
+    { ...targetProps, ...hoverHandlers },
+    { ...tooltipProps, visible },
+  ]
+}

package/src/tooltips/usePopper.ts

@@ -0,0 +1,87 @@
+import { useRef, useLayoutEffect } from 'react'
+import { createPopper } from '@popperjs/core'
+
+import type {
+  UsePopperOptions,
+  UsePopperResult,
+  PopperOptions,
+  PopperModifer,
+  HandleStateUpdate,
+} from './types'
+
+const DISABLED_APPLY_STYLES_MODIFIER = {
+  name: 'applyStyles',
+  enabled: false,
+}
+
+const makeUpdateStateModifier = (
+  handleStateUpdate: HandleStateUpdate
+): PopperModifer<{}> => ({
+  name: 'updateUsePopperState',
+  enabled: true,
+  phase: 'write',
+  fn: ({ state }) => {
+    handleStateUpdate(state.placement, state.styles)
+  },
+})
+
+const makeOffsetModifier = (offset: number): Partial<PopperModifer<{}>> => ({
+  name: 'offset',
+  options: { offset: [0, offset] },
+})
+
+const makeArrowModifier = (arrow: Element): Partial<PopperModifer<{}>> => ({
+  name: 'arrow',
+  options: { element: arrow },
+})
+
+export function usePopper(options: UsePopperOptions): UsePopperResult {
+  const {
+    target,
+    tooltip,
+    arrow,
+    placement,
+    strategy,
+    offset,
+    onStateUpdate,
+  } = options
+
+  const popperRef = useRef<UsePopperResult | null>(null)
+
+  // useLayoutEffect instead of useEffect to avoid positioning flash
+  useLayoutEffect(() => {
+    if (target && tooltip) {
+      const options: Partial<PopperOptions> &
+        Pick<PopperOptions, 'modifiers'> = {
+        modifiers: [
+          DISABLED_APPLY_STYLES_MODIFIER,
+          makeUpdateStateModifier(onStateUpdate),
+        ],
+      }
+
+      if (offset != null) {
+        options.modifiers.push(makeOffsetModifier(offset))
+      }
+
+      if (arrow) {
+        options.modifiers.push(makeArrowModifier(arrow))
+      }
+
+      if (placement != null) options.placement = placement
+      if (strategy != null) options.strategy = strategy
+
+      const popperInstance = createPopper(target, tooltip, options)
+
+      // immediately force a synchronous update to avoid positioning flash
+      popperInstance.forceUpdate()
+      popperRef.current = popperInstance
+
+      return () => {
+        popperInstance.destroy()
+        popperRef.current = null
+      }
+    }
+  }, [target, tooltip, arrow, placement, strategy, offset, onStateUpdate])
+
+  return popperRef.current
+}

package/src/tooltips/useTooltip.ts

@@ -0,0 +1,100 @@
+import { useState, useCallback, useRef } from 'react'
+import uniqueId from 'lodash/uniqueId'
+import { usePopper } from './usePopper'
+import * as Styles from './styles'
+
+import type { CSSProperties } from 'react'
+import type { UseTooltipOptions, UseTooltipResult, Placement } from './types'
+
+interface TooltipState {
+  placement: Placement | null
+  tooltipStyle: CSSProperties
+  arrowStyle: CSSProperties
+}
+
+const TOOLTIP_ID_PREFIX = 'Tooltip__'
+
+/**
+ * Hook to position a tooltip component relative to a target component
+ *
+ * @param {UseTooltipOptions} [options={}] (change the default `position`, `strategy`, or `offset` of the tooltip)
+ * @returns {UseTooltipResult}
+ * @example
+ * ```js
+ * import {
+ *   useTooltip,
+ *   Tooltip,
+ *   TOOLTIP_TOP,
+ *   TOOLTIP_FIXED
+ * } from '@opentrons/components'
+ *
+ * export function HelloWorld() {
+ *   const [targetProps, tooltipProps] = useTooltip({
+ *     position: TOOLTIP_TOP,
+ *     strategy: TOOLTIP_FIXED
+ *   })
+ *
+ *   return (
+ *     <>
+ *       <span {...targetProps}>Hello</span>
+ *       <Tooltip visible={true} {...tooltipProps}>World</Tooltip>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function useTooltip(options: UseTooltipOptions = {}): UseTooltipResult {
+  const { placement, strategy, offset = Styles.TOOLTIP_OFFSET_PX } = options
+  const tooltipId = useRef(uniqueId(TOOLTIP_ID_PREFIX)).current
+  const [target, targetRef] = useState<Element | null>(null)
+  const [tooltip, tooltipRef] = useState<HTMLElement | null>(null)
+  const [arrow, arrowRef] = useState<HTMLElement | null>(null)
+  const [tooltipState, setTooltipState] = useState<TooltipState>({
+    placement: null,
+    tooltipStyle: Styles.INITIAL_TOOLTIP_STYLE,
+    arrowStyle: Styles.INITIAL_ARROW_STYLE,
+  })
+
+  const onStateUpdate = useCallback(
+    (
+      placement: Placement | null,
+      styles: {
+        popper?: CSSProperties
+        arrow?: CSSProperties
+      }
+    ) => {
+      setTooltipState({
+        placement,
+        tooltipStyle: styles.popper ?? Styles.INITIAL_TOOLTIP_STYLE,
+        arrowStyle: styles.arrow ?? Styles.INITIAL_ARROW_STYLE,
+      })
+    },
+    []
+  )
+
+  usePopper({
+    target,
+    tooltip,
+    arrow,
+    placement,
+    strategy,
+    offset,
+    onStateUpdate,
+  })
+
+  const targetProps = {
+    ref: targetRef,
+    'aria-describedby': tooltipId,
+  }
+
+  const tooltipProps = {
+    id: tooltipId,
+    ref: tooltipRef,
+    style: tooltipState.tooltipStyle,
+    arrowStyle: tooltipState.arrowStyle,
+    placement: tooltipState.placement,
+    arrowRef,
+  }
+
+  return [targetProps, tooltipProps]
+}