@opentrons/components 0.1.6-alpha.16 → 0.1.6-alpha.17

package/src/hooks/__tests__/useScrolling.test.tsx

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useScrolling } from '../useScrolling'
+
+describe('useScrolling', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  })
+
+  it('returns false when there is no scrolling', () => {
+    const ref = document.createElement('div')
+    const { result } = renderHook(() => useScrolling(ref))
+    expect(result.current).toBe(false)
+  })
+
+  it('returns true when scrolling', () => {
+    const ref = document.createElement('div')
+    const { result } = renderHook(() => useScrolling(ref))
+    ref.scrollTop = 10
+    act(() => {
+      ref.dispatchEvent(new Event('scroll'))
+    })
+    expect(result.current).toBe(true)
+  })
+
+  it('returns false after scrolling stops', () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+    const ref = document.createElement('div')
+    const { result } = renderHook(() => useScrolling(ref))
+    ref.scrollTop = 10
+    act(() => {
+      ref.dispatchEvent(new Event('scroll'))
+    })
+    expect(result.current).toBe(true)
+    act(() => {
+      vi.advanceTimersByTime(300)
+    })
+    expect(result.current).toBe(false)
+  })
+})

package/src/hooks/__tests__/useSwipe.test.tsx

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { useSwipe } from '../useSwipe'
+
+describe('useSwipe hook', () => {
+  it('useSwipe returns UseSwipeResult object', () => {
+    const { result } = renderHook(() => useSwipe())
+    expect(result.current.style.touchAction).toBe('none')
+    expect(result.current.isEnabled).toBe(true)
+    expect(result.current.swipeType).toBe('')
+  })
+
+  it('When calling enable, isEnabled true', () => {
+    const { result } = renderHook(() => useSwipe())
+    result.current.enable()
+    expect(result.current.isEnabled).toBe(true)
+  })
+
+  it('When calling disable, isEnabled false', () => {
+    const { result } = renderHook(() => useSwipe())
+    act(() => {
+      result.current.disable()
+    })
+    expect(result.current.isEnabled).toBe(false)
+  })
+})

package/src/hooks/__tests__/useTimeout.test.tsx

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

package/src/hooks/__tests__/useToggle.test.tsx

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

package/src/hooks/index.ts

@@ -0,0 +1,15 @@
+// generic react hooks that don't fit cleanly anywhere else
+
+export * from './useConditionalConfirm'
+export * from './useDrag'
+export * from './useIdle'
+export * from './useInterval'
+export * from './useLongPress'
+export * from './useMountEffect'
+export * from './usePrevious'
+export * from './useScrolling'
+export * from './useSelectDeckLocation'
+export * from './useSwipe'
+export * from './useTimeout'
+export * from './useToggle'
+export * from './useMenuHandleClickOutside'

package/src/hooks/useConditionalConfirm.ts

@@ -0,0 +1,70 @@
+import { useState } from 'react'
+
+/**
+ * useConditionalConfirm is intended for cases where we want to block and defer
+ * a particular user action until the user clicks "ok" in any kind of "are you sure?"
+ * confirmation UI. The arguments passed to the confirm function will be preserved and
+ * used to call handleContinue. Ex. a click event is being deferred by a modal. When the
+ * user confirms, the initial click event passed as an argument will be used as the argument in
+ * the callback.
+ * @param {() => unknown)} handleContinue (the action we may want to require confirmation for)
+ * @param {boolean} shouldBlock (if no confirmation is needed, we will avoid the modal and immediately call handleContinue)
+ * @example
+ * ```js
+ * import { useConditionalConfirm } from '@opentrons/components'
+ *
+ * const ExampleDangerForm = props => {
+ * const {
+ *   confirm,
+ *   showConfirmation,
+ *   cancel,
+ *  } = useConditionalConfirm(props.goAhead, props.dangerIsPresent)
+ *
+ *  return (
+ *   <>
+ *     {showConfirmation && (
+ *       <AreYouSureModal
+ *         handleCancel={cancel}
+ *         handleContinue={confirm}
+ *       />
+ *     )}
+ *     <DangerFormFields />
+ *     <DangerousSubmit onClick={confirm} />
+ *   </>
+ *  )
+ * }
+ * ```
+ */
+
+export interface UseConditionalConfirmResult<T extends any[]> {
+  confirm: (...args: T) => void
+  showConfirmation: boolean
+  cancel: () => unknown
+}
+
+export const useConditionalConfirm = <T extends any[]>(
+  handleContinue: (...args: T) => any,
+  shouldBlock: boolean
+): UseConditionalConfirmResult<T> => {
+  const [pendingArgs, setPendingArgs] = useState<T | null>(null)
+  const pendingConfirm = pendingArgs !== null
+  const confirm: (...args: T) => void = (...confirmArgs) => {
+    if (shouldBlock && !pendingConfirm) {
+      setPendingArgs(confirmArgs)
+    } else {
+      // call handleContinue with pending args if we have them
+      const handleContinueArgs =
+        pendingArgs !== null ? pendingArgs : confirmArgs
+      handleContinue(...handleContinueArgs)
+      setPendingArgs(null)
+    }
+  }
+
+  return {
+    confirm,
+    showConfirmation: pendingConfirm,
+    cancel: () => {
+      setPendingArgs(null)
+    },
+  }
+}

package/src/hooks/useDrag.ts

@@ -0,0 +1,90 @@
+import { useState, useEffect, useRef } from 'react'
+import interact from 'interactjs'
+import type { CSSProperties, MutableRefObject } from 'react'
+
+export interface ElementPosition {
+  width: number
+  height: number
+  x: number
+  y: number
+}
+
+export interface UseDragResult {
+  ref: MutableRefObject<null>
+  style: CSSProperties
+  position: ElementPosition
+  isEnabled: boolean
+  enable: () => void
+  disable: () => void
+}
+
+/**
+ * useDrag makes HTMLElement draggable for on-device app
+ * This hook should be used when isOnDevice is true
+ * @param {ElementPosition} (width, height, x, and y, they are HTMLElement's size and the initial position)
+ * @returns {UseDragResult}
+ */
+
+export const useDrag = (position: ElementPosition): UseDragResult => {
+  const [elementPosition, setElementPosition] = useState<ElementPosition>(
+    position
+  )
+  const [isEnabled, setIsEnabled] = useState<boolean>(true)
+  const interactiveRef = useRef(null)
+  let { x, y, width, height } = elementPosition
+
+  const enable = (): void => {
+    if (interactiveRef?.current != null) {
+      interact((interactiveRef.current as unknown) as HTMLElement)
+        .draggable({
+          modifiers: [],
+          inertia: false,
+        })
+        .on('dragmove', (event: Interact.InteractEvent) => {
+          x += Number(event.dx)
+          y += Number(event.dy)
+
+          setElementPosition({
+            width,
+            height,
+            x,
+            y,
+          })
+        })
+    }
+  }
+  const disable = (): void => {
+    if (interactiveRef?.current != null) {
+      interact((interactiveRef.current as unknown) as HTMLElement).unset()
+    }
+  }
+
+  useEffect(() => {
+    if (isEnabled) {
+      enable()
+    } else {
+      disable()
+    }
+    return disable
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isEnabled])
+
+  return {
+    ref: interactiveRef,
+    style: {
+      transform: `translate3D(${elementPosition.x}px, ${elementPosition.y}px, 0)`,
+      width: `${elementPosition.width}px`,
+      height: `${elementPosition.height}px`,
+      position: 'absolute' as React.CSSProperties['position'],
+      touchAction: 'none',
+    },
+    position: elementPosition,
+    isEnabled,
+    enable: () => {
+      setIsEnabled(true)
+    },
+    disable: () => {
+      setIsEnabled(false)
+    },
+  }
+}

package/src/hooks/useIdle.ts

@@ -0,0 +1,68 @@
+import { useState, useEffect, useRef } from 'react'
+
+const USER_EVENTS: Array<keyof DocumentEventMap> = [
+  'click',
+  'dblclick',
+  'keypress',
+  'mousemove',
+  'pointerover',
+  'pointerenter',
+  'pointerdown',
+  'pointermove',
+  'pointerout',
+  'pointerleave',
+  'scroll',
+  'touchmove',
+  'touchstart',
+  'mousedown',
+]
+
+const DEFAULT_OPTIONS = {
+  events: USER_EVENTS,
+  initialState: true,
+}
+
+/**
+ * React hook to check user events
+ *
+ * @param {number} idleTime (idle time)
+ * @param {object} options (events that the app need to check, initialState: initial state true => idle)
+ * @returns {boolean}
+ */
+export function useIdle(
+  idleTime: number,
+  options?: Partial<{
+    events: Array<keyof DocumentEventMap>
+    initialState: boolean
+  }>
+): boolean {
+  const { events, initialState } = { ...DEFAULT_OPTIONS, ...options }
+  const [idle, setIdle] = useState<boolean>(initialState)
+  const idleTimer = useRef<number>()
+
+  useEffect(() => {
+    const handleEvents = (): void => {
+      setIdle(false)
+
+      if (idleTimer.current != null) {
+        window.clearTimeout(idleTimer.current)
+      }
+
+      idleTimer.current = window.setTimeout(() => {
+        setIdle(true)
+      }, idleTime)
+    }
+
+    events.forEach(event => {
+      document.addEventListener(event, handleEvents)
+    })
+
+    return () => {
+      events.forEach(event => {
+        document.removeEventListener(event, handleEvents)
+      })
+    }
+  }, [events, idleTime])
+
+  return idle
+}

package/src/hooks/useInterval.ts

@@ -0,0 +1,38 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * React hook to call a function on an interval; copied from:
+ * https://overreacted.io/making-setinterval-declarative-with-react-hooks/
+ *
+ * @template T (type of the input value)
+ * @param {() => unknown} callback (function to call on an interval)
+ * @param {number | null} delay (interval delay, or null to stop interval)
+ * @param {boolean} [immediate=false] (trigger the callback immediately before starting the interval)
+ * @returns {void}
+ */
+export function useInterval(
+  callback: () => unknown,
+  delay: number | null,
+  immediate: boolean = false
+): void {
+  const savedCallback: React.MutableRefObject<
+    (() => unknown) | undefined
+  > = useRef()
+
+  // remember the latest callback
+  useEffect(() => {
+    savedCallback.current = callback
+  }, [callback])
+
+  // set up the interval
+  useEffect(() => {
+    const tick = (): unknown => savedCallback.current && savedCallback.current()
+    if (delay !== null && delay > 0) {
+      if (immediate) tick()
+      const id = setInterval(tick, delay)
+      return () => {
+        clearInterval(id)
+      }
+    }
+  }, [delay, immediate])
+}

package/src/hooks/useLongPress.ts

@@ -0,0 +1,83 @@
+import { useState, useEffect, useRef } from 'react'
+import interact from 'interactjs'
+import type PointerEvent from 'interactjs'
+import type { CSSProperties, MutableRefObject } from 'react'
+
+const HOLD_DURATION_MS = 1000
+
+// Note kj 12/05/2022
+// ODD needs setIsLongPressed since when a user use long press, ODD app needs to show overflow menu.
+// Then if a user takes clicking outside action, the ODD app needs to reset the isLongPressed.
+// In terms of setIsTapped, if the ODD app doesn't need it, it will be removed.
+export interface UseLongPressResult {
+  ref: MutableRefObject<null>
+  style: CSSProperties
+  isEnabled: boolean
+  isLongPressed: boolean
+  isTapped: boolean
+  setIsLongPressed: (value: boolean) => void
+  setIsTapped: (value: boolean) => void
+  enable: () => void
+  disable: () => void
+}
+
+/**
+ * useLongPress provide two actions (tap and long press)
+ * useLongPress recognize 1 sec hold as long press: hold Duration
+ * interactjs recognize "hold" when an element is held down around 600ms(default)
+ * @returns {UseLongPressResult}
+ */
+export const useLongPress = (): UseLongPressResult => {
+  const [isLongPressed, setIsLongPressed] = useState<boolean>(false)
+  const [isTapped, setIsTapped] = useState<boolean>(false)
+  const [isEnabled, setIsEnabled] = useState<boolean>(true)
+  const interactiveRef = useRef(null)
+
+  const enable = (): void => {
+    if (interactiveRef?.current != null) {
+      interact((interactiveRef.current as unknown) as HTMLElement)
+        .pointerEvents({
+          holdDuration: HOLD_DURATION_MS,
+        })
+        .on('hold', (_event: PointerEvent) => {
+          setIsLongPressed(isLongPressed => !isLongPressed)
+        })
+        .on('tap', (_event: PointerEvent) => {
+          setIsTapped(isTapped => !isTapped)
+        })
+    }
+  }
+  const disable = (): void => {
+    if (interactiveRef?.current != null) {
+      interact((interactiveRef.current as unknown) as HTMLElement).unset()
+    }
+  }
+
+  useEffect(() => {
+    if (isEnabled) {
+      enable()
+    } else {
+      disable()
+    }
+    return disable
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isEnabled])
+
+  return {
+    ref: interactiveRef,
+    style: {
+      touchAction: 'none',
+    },
+    isEnabled,
+    isLongPressed,
+    isTapped,
+    setIsLongPressed,
+    setIsTapped,
+    enable: () => {
+      setIsEnabled(true)
+    },
+    disable: () => {
+      setIsEnabled(false)
+    },
+  }
+}

package/src/hooks/useMenuHandleClickOutside.tsx

@@ -0,0 +1,46 @@
+import { useState } from 'react'
+import { COLORS } from '../helix-design-system'
+import { Overlay } from '../modals'
+
+import type { Dispatch, MouseEventHandler, SetStateAction } from 'react'
+
+interface MenuHandleClickOutside {
+  menuOverlay: JSX.Element
+  handleOverflowClick: MouseEventHandler<HTMLButtonElement>
+  showOverflowMenu: boolean
+  setShowOverflowMenu: Dispatch<SetStateAction<boolean>>
+}
+
+export function useMenuHandleClickOutside(): MenuHandleClickOutside {
+  const [showOverflowMenu, setShowOverflowMenu] = useState<boolean>(false)
+
+  const handleOverflowClick: MouseEventHandler<HTMLButtonElement> = e => {
+    e.preventDefault()
+    e.stopPropagation()
+    setShowOverflowMenu(currentShowOverflowMenu => !currentShowOverflowMenu)
+  }
+
+  const handleClickOutside: MouseEventHandler<HTMLDivElement> = e => {
+    e.preventDefault()
+    e.stopPropagation()
+    setShowOverflowMenu(false)
+  }
+
+  const menuOverlay: JSX.Element = (
+    <>
+      {showOverflowMenu ? (
+        <Overlay
+          onClick={handleClickOutside}
+          backgroundColor={COLORS.transparent}
+        />
+      ) : null}
+    </>
+  )
+
+  return {
+    menuOverlay,
+    handleOverflowClick,
+    showOverflowMenu,
+    setShowOverflowMenu,
+  }
+}

package/src/hooks/useMountEffect.ts

@@ -0,0 +1,12 @@
+import { useEffect } from 'react'
+import type { EffectCallback } from 'react'
+/**
+ * React hook to call a function on component mount and unmount
+ *
+ * @param {EffectCallback} callback (function to call on mount that optionally returns a cleanup function to call on unmount)
+ * @returns {void}
+ */
+export function useMountEffect(callback: EffectCallback): void {
+  // call useEffect with an empty dependency list so it's only called on mount
+  useEffect(callback, [])
+}

package/src/hooks/usePrevious.ts

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from 'react'
+
+/**
+ * React hook to keep track of the previous value of a parameter
+ * https://reactjs.org/docs/hooks-faq.html#how-to-get-the-previous-props-or-state
+ *
+ * @template T (type of the input value)
+ * @param {T} value (value to keep track of)
+ * @returns {(T | void)} (previous value or undefined if first render)
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const prevRef = useRef<T | undefined>()
+
+  useEffect(() => {
+    prevRef.current = value
+  }, [value])
+
+  return prevRef.current
+}

package/src/hooks/useScrolling.ts

@@ -0,0 +1,33 @@
+/**
+ * A custom hook that detects whether an HTMLElement is being scrolled.
+ *
+ * @param {HTMLElement | null} node - HTMLElement to monitor for scrolling.
+ * @returns {boolean} - A boolean indicating whether the HTMLElement is being scrolled.
+ */
+import { useState, useEffect, useRef } from 'react'
+
+export const useScrolling = (node: HTMLElement | null): boolean => {
+  const [isScrolling, setIsScrolling] = useState<boolean>(false)
+  const scrollTimeout = useRef<NodeJS.Timeout | null>(null)
+
+  useEffect(() => {
+    if (node != null) {
+      const handleScroll = (): void => {
+        setIsScrolling(true)
+        if (scrollTimeout.current != null) clearTimeout(scrollTimeout.current)
+        scrollTimeout.current = setTimeout(() => {
+          setIsScrolling(false)
+        }, 200)
+      }
+
+      node?.addEventListener('scroll', handleScroll)
+
+      return () => {
+        if (scrollTimeout.current != null) clearTimeout(scrollTimeout.current)
+        node?.removeEventListener('scroll', handleScroll)
+      }
+    }
+  }, [node])
+
+  return isScrolling
+}

package/src/hooks/useSelectDeckLocation/SelectDeckLocation.stories.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react'
+import { DeckLocationSelect as DeckLocationSelectComponent } from './'
+import {
+  FLEX_ROBOT_TYPE,
+  getDeckDefFromRobotType,
+  OT2_ROBOT_TYPE,
+} from '@opentrons/shared-data'
+
+import type { Meta, StoryObj } from '@storybook/react'
+import type { RobotType } from '@opentrons/shared-data'
+
+const meta: Meta<React.ComponentProps<typeof DeckLocationSelectComponent>> = {
+  component: DeckLocationSelectComponent,
+  title: 'Library/Molecules/Simulation/SelectDeckLocation',
+} as Meta
+
+export default meta
+type Story = StoryObj<{ disabledSlotNames: string[]; robotType: RobotType }>
+
+export const FlexDeckLocationSelect: Story = {
+  render: args => {
+    return <Wrapper {...args} />
+  },
+  args: {
+    disabledSlotNames: ['A2'],
+    robotType: FLEX_ROBOT_TYPE,
+  },
+}
+
+export const OT2DeckLocationSelect: Story = {
+  render: args => {
+    return <Wrapper {...args} />
+  },
+  args: {
+    disabledSlotNames: ['2'],
+    robotType: OT2_ROBOT_TYPE,
+  },
+}
+
+function Wrapper(props: {
+  disabledSlotNames: string[]
+  robotType: RobotType
+}): JSX.Element {
+  const [selectedLocation, setSelectedLocation] = React.useState({
+    slotName: props.robotType === FLEX_ROBOT_TYPE ? 'A1' : '1',
+  })
+
+  const deckDef = getDeckDefFromRobotType(props.robotType)
+  return (
+    <DeckLocationSelectComponent
+      {...{ selectedLocation, setSelectedLocation, deckDef }}
+      disabledLocations={props.disabledSlotNames.map(s => ({ slotName: s }))}
+    />
+  )
+}