@primer/components 30.3.0-rc.2010c7d4 → 31.0.0-rc.15aa0a10

package/lib-esm/__tests__/behaviors/scrollIntoViewingArea.test.js

@@ -0,0 +1,224 @@
+import { scrollIntoViewingArea } from '../../behaviors/scrollIntoViewingArea';
+
+function scrollPositionFormula(positionData, isChildAboveViewingArea) {
+  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, y, width, height) {
+  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, childRect) {
+  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, 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, 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, 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, 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, viewingArea, 'horizontal', scrollMargin, scrollMargin, 'auto');
+      expect(scrollToMock).toHaveBeenCalledWith({
+        behavior: 'auto',
+        left: expectedScrollPosition
+      });
+    });
+  });
+});

package/lib-esm/behaviors/scrollIntoViewingArea.d.ts

@@ -0,0 +1 @@
+export declare const scrollIntoViewingArea: (child: HTMLElement, viewingArea: HTMLElement, direction?: 'horizontal' | 'vertical', startMargin?: number, endMargin?: number, behavior?: ScrollBehavior) => void;

package/lib-esm/behaviors/scrollIntoViewingArea.js

@@ -0,0 +1,30 @@
+export const scrollIntoViewingArea = (child, viewingArea, direction = 'vertical', startMargin = 8, endMargin = 0, behavior = '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/lib-esm/hooks/useOpenAndCloseFocus.d.ts

@@ -3,5 +3,6 @@ export declare type UseOpenAndCloseFocusSettings = {
     initialFocusRef?: React.RefObject<HTMLElement>;
     containerRef: React.RefObject<HTMLElement>;
     returnFocusRef: React.RefObject<HTMLElement>;
+    preventFocusOnOpen?: boolean;
 };
-export declare function useOpenAndCloseFocus({ initialFocusRef, returnFocusRef, containerRef }: UseOpenAndCloseFocusSettings): void;
+export declare function useOpenAndCloseFocus({ initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen }: UseOpenAndCloseFocusSettings): void;

package/lib-esm/hooks/useOpenAndCloseFocus.js

@@ -3,9 +3,14 @@ import { iterateFocusableElements } from '../utils/iterateFocusableElements';
 export function useOpenAndCloseFocus({
   initialFocusRef,
   returnFocusRef,
-  containerRef
+  containerRef,
+  preventFocusOnOpen
 }) {
   useEffect(() => {
+    if (preventFocusOnOpen) {
+      return;
+    }
+
     const returnRef = returnFocusRef.current;
 
     if (initialFocusRef && initialFocusRef.current) {
@@ -18,5 +23,5 @@ export function useOpenAndCloseFocus({
     return function () {
       returnRef === null || returnRef === void 0 ? void 0 : returnRef.focus();
     };
-  }, [initialFocusRef, returnFocusRef, containerRef]);
+  }, [initialFocusRef, returnFocusRef, containerRef, preventFocusOnOpen]);
 }

package/lib-esm/hooks/useOverlay.d.ts

@@ -7,8 +7,9 @@ export declare type UseOverlaySettings = {
     onEscape: (e: KeyboardEvent) => void;
     onClickOutside: (e: TouchOrMouseEvent) => void;
     overlayRef?: React.RefObject<HTMLDivElement>;
+    preventFocusOnOpen?: boolean;
 };
 export declare type OverlayReturnProps = {
     ref: React.RefObject<HTMLDivElement>;
 };
-export declare const useOverlay: ({ overlayRef: _overlayRef, returnFocusRef, initialFocusRef, onEscape, ignoreClickRefs, onClickOutside }: UseOverlaySettings) => OverlayReturnProps;
+export declare const useOverlay: ({ overlayRef: _overlayRef, returnFocusRef, initialFocusRef, onEscape, ignoreClickRefs, onClickOutside, preventFocusOnOpen }: UseOverlaySettings) => OverlayReturnProps;

package/lib-esm/hooks/useOverlay.js

@@ -8,13 +8,15 @@ export const useOverlay = ({
   initialFocusRef,
   onEscape,
   ignoreClickRefs,
-  onClickOutside
+  onClickOutside,
+  preventFocusOnOpen
 }) => {
   const overlayRef = useProvidedRefOrCreate(_overlayRef);
   useOpenAndCloseFocus({
     containerRef: overlayRef,
     returnFocusRef,
-    initialFocusRef
+    initialFocusRef,
+    preventFocusOnOpen
   });
   useOnOutsideClick({
     containerRef: overlayRef,

package/lib-esm/index.d.ts

@@ -24,6 +24,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';

package/lib-esm/index.js

@@ -19,6 +19,7 @@ export { useConfirm } from './Dialog/ConfirmationDialog'; // Components
 
 export { ActionList } from './ActionList';
 export { ActionMenu } from './ActionMenu';
+export { default as Autocomplete } from './Autocomplete';
 export { default as Avatar } from './Avatar';
 export { default as AvatarPair } from './AvatarPair';
 export { default as AvatarStack } from './AvatarStack';