@primer/components 30.3.0-rc.2010c7d4 → 30.3.0-rc.9dbc85a9

package/src/__tests__/behaviors/scrollIntoViewingArea.test.ts

@@ -0,0 +1,195 @@
+import {scrollIntoViewingArea} from '../../behaviors/scrollIntoViewingArea'
+
+function scrollPositionFormula(
+  positionData: {viewingAreaEdgePosition: number; childEdgePosition: number; margin: number},
+  isChildAboveViewingArea: boolean
+) {
+  const {viewingAreaEdgePosition, childEdgePosition, margin} = positionData
+  const marginOffset = margin * (isChildAboveViewingArea ? -1 : 1)
+
+  return childEdgePosition - viewingAreaEdgePosition + marginOffset
+}
+
+// The DOMRect constructor isn't available in JSDOM, so we improvise here.
+function makeDOMRect(x: number, y: number, width: number, height: number): DOMRect {
+  return {
+    x,
+    y,
+    width,
+    height,
+    top: y,
+    left: x,
+    right: x + width,
+    bottom: y + height,
+    toJSON() {
+      return this
+    }
+  }
+}
+
+// Since Jest/JSDOM doesn't support layout, we can stub out getBoundingClientRect if we know the
+// correct dimensions. JSDOM will handle the rest of the DOM API used by getAnchoredPosition.
+function createVirtualDOM(viewingAreaRect: DOMRect, childRect: DOMRect) {
+  const viewingArea = document.createElement('div')
+  viewingArea.style.overflow = 'auto'
+  viewingArea.id = 'viewingArea'
+  // eslint-disable-next-line github/unescaped-html-literal
+  viewingArea.innerHTML = '<div id="child"></div>'
+  const child = viewingArea.querySelector('#child')!
+  child.getBoundingClientRect = () => childRect
+  viewingArea.getBoundingClientRect = () => viewingAreaRect
+  return {viewingArea, child}
+}
+
+describe('scrollIntoViewingArea', () => {
+  it('scrolls the expected amount when only the viewingArea element and child element are passed to the function', () => {
+    const scrollToMock = jest.fn()
+    Object.defineProperty(window.Element.prototype, 'scrollTo', {
+      writable: true,
+      value: scrollToMock
+    })
+    const childHeight = 50
+    const viewAreaHeight = 100
+    const childStart = viewAreaHeight + 10
+    const expectedScrollPosition = scrollPositionFormula(
+      {viewingAreaEdgePosition: viewAreaHeight, childEdgePosition: childStart + childHeight, margin: 8},
+      false
+    )
+
+    const viewingAreaRect = makeDOMRect(0, 0, 100, viewAreaHeight)
+    const childRect = makeDOMRect(0, childStart, 100, childHeight)
+    const {viewingArea, child} = createVirtualDOM(viewingAreaRect, childRect)
+
+    viewingArea.getBoundingClientRect = () => viewingAreaRect
+    viewingArea.scrollTop = 0
+    child.getBoundingClientRect = () => childRect
+
+    scrollIntoViewingArea(child as HTMLDivElement, viewingArea)
+    expect(scrollToMock).toHaveBeenCalledWith({
+      behavior: 'smooth',
+      top: expectedScrollPosition
+    })
+  })
+
+  describe('y-axis', () => {
+    it('scrolls the child into the viewing area when it is AFTER the overflow cutoff point', () => {
+      const scrollToMock = jest.fn()
+      Object.defineProperty(window.Element.prototype, 'scrollTo', {
+        writable: true,
+        value: scrollToMock
+      })
+      const childHeight = 50
+      const viewAreaHeight = 100
+      const childStart = viewAreaHeight + 10
+      const scrollMargin = 10
+      const expectedScrollPosition = scrollPositionFormula(
+        {viewingAreaEdgePosition: viewAreaHeight, childEdgePosition: childStart + childHeight, margin: scrollMargin},
+        false
+      )
+
+      const viewingAreaRect = makeDOMRect(0, 0, 100, viewAreaHeight)
+      const childRect = makeDOMRect(0, childStart, 100, childHeight)
+      const {viewingArea, child} = createVirtualDOM(viewingAreaRect, childRect)
+
+      viewingArea.getBoundingClientRect = () => viewingAreaRect
+      viewingArea.scrollTop = 0
+      child.getBoundingClientRect = () => childRect
+
+      scrollIntoViewingArea(child as HTMLDivElement, viewingArea, 'vertical', scrollMargin, scrollMargin, 'auto')
+      expect(scrollToMock).toHaveBeenCalledWith({
+        behavior: 'auto',
+        top: expectedScrollPosition
+      })
+    })
+
+    it('scrolls the child into the viewing area when it is BEFORE the overflow cutoff point', () => {
+      const scrollToMock = jest.fn()
+      Object.defineProperty(window.Element.prototype, 'scrollTo', {
+        writable: true,
+        value: scrollToMock
+      })
+      const childHeight = 50
+      const childStart = childHeight * -1 - 10
+      const scrollMargin = 10
+      const expectedScrollPosition = scrollPositionFormula(
+        {viewingAreaEdgePosition: 0, childEdgePosition: childStart, margin: scrollMargin},
+        true
+      )
+
+      const viewingAreaRect = makeDOMRect(0, 0, 100, 100)
+      const childRect = makeDOMRect(0, childStart, 100, childHeight)
+      const {viewingArea, child} = createVirtualDOM(viewingAreaRect, childRect)
+
+      viewingArea.getBoundingClientRect = () => viewingAreaRect
+      viewingArea.scrollTop = 0
+      child.getBoundingClientRect = () => childRect
+
+      scrollIntoViewingArea(child as HTMLDivElement, viewingArea, 'vertical', scrollMargin, scrollMargin, 'auto')
+      expect(scrollToMock).toHaveBeenCalledWith({
+        behavior: 'auto',
+        top: expectedScrollPosition
+      })
+    })
+  })
+
+  describe('x-axis', () => {
+    it('scrolls the child into the viewing area when it is AFTER the overflow cutoff point', () => {
+      const scrollToMock = jest.fn()
+      Object.defineProperty(window.Element.prototype, 'scrollTo', {
+        writable: true,
+        value: scrollToMock
+      })
+      const childWidth = 50
+      const viewAreaWidth = 100
+      const childStart = viewAreaWidth + 10
+      const scrollMargin = 10
+      const expectedScrollPosition = scrollPositionFormula(
+        {viewingAreaEdgePosition: viewAreaWidth, childEdgePosition: childStart + childWidth, margin: scrollMargin},
+        false
+      )
+
+      const viewingAreaRect = makeDOMRect(0, 0, 100, viewAreaWidth)
+      const childRect = makeDOMRect(childStart, 0, childWidth, 100)
+      const {viewingArea, child} = createVirtualDOM(viewingAreaRect, childRect)
+
+      viewingArea.getBoundingClientRect = () => viewingAreaRect
+      viewingArea.scrollLeft = 0
+      child.getBoundingClientRect = () => childRect
+
+      scrollIntoViewingArea(child as HTMLDivElement, viewingArea, 'horizontal', scrollMargin, scrollMargin, 'auto')
+      expect(scrollToMock).toHaveBeenCalledWith({
+        behavior: 'auto',
+        left: expectedScrollPosition
+      })
+    })
+
+    it('scrolls the child into the viewing area when it is BEFORE the overflow cutoff point', () => {
+      const scrollToMock = jest.fn()
+      Object.defineProperty(window.Element.prototype, 'scrollTo', {
+        writable: true,
+        value: scrollToMock
+      })
+      const childWidth = 50
+      const childStart = childWidth * -1 - 10
+      const scrollMargin = 10
+      const expectedScrollPosition = scrollPositionFormula(
+        {viewingAreaEdgePosition: 0, childEdgePosition: childStart, margin: scrollMargin},
+        true
+      )
+
+      const viewingAreaRect = makeDOMRect(0, 0, 100, 100)
+      const childRect = makeDOMRect(childStart, 0, childWidth, 100)
+      const {viewingArea, child} = createVirtualDOM(viewingAreaRect, childRect)
+
+      viewingArea.getBoundingClientRect = () => viewingAreaRect
+      viewingArea.scrollTop = 0
+      child.getBoundingClientRect = () => childRect
+
+      scrollIntoViewingArea(child as HTMLDivElement, viewingArea, 'horizontal', scrollMargin, scrollMargin, 'auto')
+      expect(scrollToMock).toHaveBeenCalledWith({
+        behavior: 'auto',
+        left: expectedScrollPosition
+      })
+    })
+  })
+})

package/src/behaviors/scrollIntoViewingArea.ts

@@ -0,0 +1,27 @@
+export const scrollIntoViewingArea = (
+  child: HTMLElement,
+  viewingArea: HTMLElement,
+  direction: 'horizontal' | 'vertical' = 'vertical',
+  startMargin = 8,
+  endMargin = 0,
+  behavior: ScrollBehavior = 'smooth'
+) => {
+  const startSide = direction === 'vertical' ? 'top' : 'left'
+  const endSide = direction === 'vertical' ? 'bottom' : 'right'
+  const scrollSide = direction === 'vertical' ? 'scrollTop' : 'scrollLeft'
+  const {[startSide]: childStart, [endSide]: childEnd} = child.getBoundingClientRect()
+  const {[startSide]: viewingAreaStart, [endSide]: viewingAreaEnd} = viewingArea.getBoundingClientRect()
+
+  const isChildStartAboveViewingArea = childStart < viewingAreaStart + endMargin
+  const isChildBottomBelowViewingArea = childEnd > viewingAreaEnd - startMargin
+
+  if (isChildStartAboveViewingArea) {
+    const scrollHeightToChildStart = childStart - viewingAreaStart + viewingArea[scrollSide]
+    viewingArea.scrollTo({behavior, [startSide]: scrollHeightToChildStart - endMargin})
+  } else if (isChildBottomBelowViewingArea) {
+    const scrollHeightToChildBottom = childEnd - viewingAreaEnd + viewingArea[scrollSide]
+    viewingArea.scrollTo({behavior, [startSide]: scrollHeightToChildBottom + startMargin})
+  }
+
+  // either completely in view or outside viewing area on both ends, don't scroll
+}

package/src/hooks/useOpenAndCloseFocus.ts

@@ -5,14 +5,19 @@ export type UseOpenAndCloseFocusSettings = {
   initialFocusRef?: React.RefObject<HTMLElement>
   containerRef: React.RefObject<HTMLElement>
   returnFocusRef: React.RefObject<HTMLElement>
+  preventFocusOnOpen?: boolean
 }
 
 export function useOpenAndCloseFocus({
   initialFocusRef,
   returnFocusRef,
-  containerRef
+  containerRef,
+  preventFocusOnOpen
 }: UseOpenAndCloseFocusSettings): void {
   useEffect(() => {
+    if (preventFocusOnOpen) {
+      return
+    }
     const returnRef = returnFocusRef.current
     if (initialFocusRef && initialFocusRef.current) {
       initialFocusRef.current.focus()
@@ -23,5 +28,5 @@ export function useOpenAndCloseFocus({
     return function () {
       returnRef?.focus()
     }
-  }, [initialFocusRef, returnFocusRef, containerRef])
+  }, [initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen])
 }

package/src/hooks/useOverlay.tsx

@@ -10,6 +10,7 @@ export type UseOverlaySettings = {
   onEscape: (e: KeyboardEvent) => void
   onClickOutside: (e: TouchOrMouseEvent) => void
   overlayRef?: React.RefObject<HTMLDivElement>
+  preventFocusOnOpen?: boolean
 }
 
 export type OverlayReturnProps = {
@@ -22,10 +23,11 @@ export const useOverlay = ({
   initialFocusRef,
   onEscape,
   ignoreClickRefs,
-  onClickOutside
+  onClickOutside,
+  preventFocusOnOpen
 }: UseOverlaySettings): OverlayReturnProps => {
   const overlayRef = useProvidedRefOrCreate<HTMLDivElement>(_overlayRef)
-  useOpenAndCloseFocus({containerRef: overlayRef, returnFocusRef, initialFocusRef})
+  useOpenAndCloseFocus({containerRef: overlayRef, returnFocusRef, initialFocusRef, preventFocusOnOpen})
   useOnOutsideClick({containerRef: overlayRef, ignoreClickRefs, onClickOutside})
   useOnEscapePress(onEscape)
   return {ref: overlayRef}

package/src/index.ts

@@ -30,6 +30,8 @@ export {useConfirm} from './Dialog/ConfirmationDialog'
 export {ActionList} from './ActionList'
 export {ActionMenu} from './ActionMenu'
 export type {ActionMenuProps} from './ActionMenu'
+export {default as Autocomplete} from './Autocomplete'
+export type {AutocompleteMenuProps, AutocompleteInputProps, AutocompleteOverlayProps} from './Autocomplete'
 export {default as Avatar} from './Avatar'
 export type {AvatarProps} from './Avatar'
 export {default as AvatarPair} from './AvatarPair'