@primer/components 32.1.0 → 33.0.0-rc.b495ba4a

package/src/Autocomplete/AutocompleteMenu.tsx

@@ -0,0 +1,341 @@
+import React, {useContext, useEffect, useMemo, useRef, useState} from 'react'
+import {ActionList, ItemProps} from '../ActionList'
+import {useFocusZone} from '../hooks/useFocusZone'
+import {ComponentProps, MandateProps} from '../utils/types'
+import {Box, Spinner} from '../'
+import {AutocompleteContext} from './AutocompleteContext'
+import {PlusIcon} from '@primer/octicons-react'
+import {uniqueId} from '../utils/uniqueId'
+import {scrollIntoViewingArea} from '../behaviors/scrollIntoViewingArea'
+
+type OnSelectedChange<T> = (item: T | T[]) => void
+type AutocompleteMenuItem = MandateProps<ItemProps, 'id'>
+
+const getDefaultSortFn =
+  (isItemSelectedFn: (itemId: string | number) => boolean) => (itemIdA: string | number, itemIdB: string | number) =>
+    isItemSelectedFn(itemIdA) === isItemSelectedFn(itemIdB) ? 0 : isItemSelectedFn(itemIdA) ? -1 : 1
+
+function getDefaultItemFilter<T extends AutocompleteMenuItem>(filterValue: string) {
+  return function (item: T, _i: number) {
+    return Boolean(item.text?.toLowerCase().startsWith(filterValue.toLowerCase()))
+  }
+}
+
+function getDefaultOnSelectionChange<T extends AutocompleteMenuItem>(
+  setInputValueFn: (value: string) => void
+): OnSelectedChange<T> {
+  return function (itemOrItems) {
+    const {text = ''} = Array.isArray(itemOrItems) ? itemOrItems.slice(-1)[0] : itemOrItems
+    setInputValueFn(text)
+  }
+}
+
+const isItemSelected = (itemId: string | number, selectedItemIds: Array<string | number>) =>
+  selectedItemIds.includes(itemId)
+
+function getItemById<T extends AutocompleteMenuItem>(itemId: string | number, items: T[]) {
+  return items.find(item => item.id === itemId)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AutocompleteItemProps<T = Record<string, any>> = AutocompleteMenuItem & {metadata?: T}
+
+export type AutocompleteMenuInternalProps<T extends AutocompleteItemProps> = {
+  /**
+   * A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop.
+   * This menu item gets appended to the end of the list of options.
+   */
+  // TODO: rethink this part of the component API. this is kind of weird and confusing to use
+  // TODO: rethink `addNewItem` prop name
+  addNewItem?: Omit<T, 'onAction' | 'leadingVisual' | 'id'> & {
+    handleAddItem: (item: Omit<T, 'onAction' | 'leadingVisual'>) => void
+  }
+
+  /**
+   * The text that appears in the menu when there are no options in the array passed to the `items` prop.
+   */
+  emptyStateText?: React.ReactNode | false
+
+  /**
+   * A custom function used to filter the options in the array passed to the `items` prop.
+   * By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive.
+   */
+  filterFn?: (item: T, i: number) => boolean
+
+  /**
+   * The options for field values that are displayed in the dropdown menu.
+   * One or more may be selected depending on the value of the `selectionVariant` prop.
+   */
+  items: T[]
+
+  /**
+   * Whether the data is loaded for the menu items
+   */
+  loading?: boolean
+
+  /**
+   * The IDs of the selected items
+   */
+  // NOTE: this diverges from the SelectPanel component API, where we pass an array of objects to the `selected` prop
+  selectedItemIds: Array<string | number>
+
+  /**
+   * The sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu.
+   * By default, selected items are sorted to the top after the user closes the menu.
+   */
+  sortOnCloseFn?: (itemIdA: string | number, itemIdB: string | number) => number
+
+  /**
+   * Whether there can be one item selected from the menu or multiple items selected from the menu
+   */
+  selectionVariant?: 'single' | 'multiple'
+
+  /**
+   * Function that gets called when the menu is opened or closed
+   */
+  onOpenChange?: (open: boolean) => void
+
+  /**
+   * The function that is called when an item in the list is selected or deselected
+   */
+  onSelectedChange?: OnSelectedChange<T>
+
+  /**
+   * If the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component,
+   * pass the ref of that element to `customScrollContainerRef` to ensure the container automatically
+   * scrolls when the user highlights an item in the menu that is outside the scroll container
+   */
+  customScrollContainerRef?: React.MutableRefObject<HTMLElement | null>
+} & Pick<React.AriaAttributes, 'aria-labelledby'>
+
+function AutocompleteMenu<T extends AutocompleteItemProps>(props: AutocompleteMenuInternalProps<T>) {
+  const autocompleteContext = useContext(AutocompleteContext)
+  if (autocompleteContext === null) {
+    throw new Error('AutocompleteContext returned null values')
+  }
+  const {
+    activeDescendantRef,
+    id,
+    inputRef,
+    inputValue = '',
+    scrollContainerRef,
+    setAutocompleteSuggestion,
+    setShowMenu,
+    setInputValue,
+    setIsMenuDirectlyActivated,
+    setSelectedItemLength,
+    showMenu
+  } = autocompleteContext
+  const {
+    items,
+    selectedItemIds,
+    sortOnCloseFn,
+    emptyStateText,
+    addNewItem,
+    loading,
+    selectionVariant,
+    filterFn,
+    'aria-labelledby': ariaLabelledBy,
+    onOpenChange,
+    onSelectedChange,
+    customScrollContainerRef
+  } = props
+  const listContainerRef = useRef<HTMLDivElement>(null)
+  const [highlightedItem, setHighlightedItem] = useState<T>()
+  const [sortedItemIds, setSortedItemIds] = useState<Array<number | string>>(items.map(({id: itemId}) => itemId))
+
+  const selectableItems = useMemo(
+    () =>
+      items.map(selectableItem => {
+        return {
+          ...selectableItem,
+          role: 'option',
+          id: selectableItem.id,
+          selected: selectionVariant === 'multiple' ? selectedItemIds.includes(selectableItem.id) : undefined,
+          onAction: (item: T) => {
+            const otherSelectedItemIds = selectedItemIds.filter(selectedItemId => selectedItemId !== item.id)
+            const newSelectedItemIds = selectedItemIds.includes(item.id)
+              ? otherSelectedItemIds
+              : [...otherSelectedItemIds, item.id]
+            const onSelectedChangeFn = onSelectedChange ? onSelectedChange : getDefaultOnSelectionChange(setInputValue)
+
+            onSelectedChangeFn(
+              newSelectedItemIds.map(newSelectedItemId => getItemById(newSelectedItemId, items)) as T[]
+            )
+
+            if (selectionVariant === 'multiple') {
+              setInputValue('')
+              setAutocompleteSuggestion('')
+            } else {
+              setShowMenu(false)
+              inputRef.current?.setSelectionRange(inputRef.current.value.length, inputRef.current.value.length)
+            }
+          }
+        }
+      }),
+    [
+      items,
+      selectedItemIds,
+      inputRef,
+      onSelectedChange,
+      selectionVariant,
+      setAutocompleteSuggestion,
+      setInputValue,
+      setShowMenu
+    ]
+  )
+
+  const itemSortOrderData = useMemo(
+    () =>
+      sortedItemIds.reduce<Record<string | number, number>>((acc, curr, i) => {
+        acc[curr] = i
+
+        return acc
+      }, {}),
+    [sortedItemIds]
+  )
+
+  const sortedAndFilteredItemsToRender = useMemo(
+    () =>
+      selectableItems
+        .filter(filterFn ? filterFn : getDefaultItemFilter(inputValue))
+        .sort((a, b) => itemSortOrderData[a.id] - itemSortOrderData[b.id]),
+    [selectableItems, itemSortOrderData, filterFn, inputValue]
+  )
+
+  const allItemsToRender = useMemo(
+    () => [
+      // sorted and filtered selectable items
+      ...sortedAndFilteredItemsToRender,
+
+      // menu item used for creating a token from whatever is in the text input
+      ...(addNewItem
+        ? [
+            {
+              ...addNewItem,
+              leadingVisual: () => <PlusIcon />,
+              onAction: (item: T) => {
+                // TODO: make it possible to pass a leadingVisual when using `addNewItem`
+                addNewItem.handleAddItem({...item, id: item.id || uniqueId(), leadingVisual: undefined})
+
+                if (selectionVariant === 'multiple') {
+                  setInputValue('')
+                  setAutocompleteSuggestion('')
+                }
+              }
+            }
+          ]
+        : [])
+    ],
+    [sortedAndFilteredItemsToRender, addNewItem, setAutocompleteSuggestion, selectionVariant, setInputValue]
+  )
+
+  useFocusZone(
+    {
+      containerRef: listContainerRef,
+      focusOutBehavior: 'wrap',
+      focusableElementFilter: element => {
+        return !(element instanceof HTMLInputElement)
+      },
+      activeDescendantFocus: inputRef,
+      onActiveDescendantChanged: (current, _previous, directlyActivated) => {
+        activeDescendantRef.current = current || null
+        if (current) {
+          const selectedItem = selectableItems.find(item => item.id.toString() === current.getAttribute('data-id'))
+
+          setHighlightedItem(selectedItem)
+          setIsMenuDirectlyActivated(directlyActivated)
+        }
+
+        if (current && customScrollContainerRef && customScrollContainerRef.current && directlyActivated) {
+          scrollIntoViewingArea(current, customScrollContainerRef.current)
+        } else if (current && scrollContainerRef.current && directlyActivated) {
+          scrollIntoViewingArea(current, scrollContainerRef.current)
+        }
+      }
+    },
+    [loading]
+  )
+
+  useEffect(() => {
+    if (highlightedItem?.text?.startsWith(inputValue) && !selectedItemIds.includes(highlightedItem.id)) {
+      setAutocompleteSuggestion(highlightedItem.text)
+    } else {
+      setAutocompleteSuggestion('')
+    }
+  }, [highlightedItem, inputValue, selectedItemIds, setAutocompleteSuggestion])
+
+  useEffect(() => {
+    const itemIdSortResult = [...sortedItemIds].sort(
+      sortOnCloseFn ? sortOnCloseFn : getDefaultSortFn(itemId => isItemSelected(itemId, selectedItemIds))
+    )
+    const sortResultMatchesState =
+      itemIdSortResult.length === sortedItemIds.length &&
+      itemIdSortResult.every((element, index) => element === sortedItemIds[index])
+
+    if (showMenu === false && !sortResultMatchesState) {
+      setSortedItemIds(itemIdSortResult)
+    }
+
+    onOpenChange && onOpenChange(Boolean(showMenu))
+  }, [showMenu, onOpenChange, selectedItemIds, sortOnCloseFn, sortedItemIds])
+
+  useEffect(() => {
+    if (selectedItemIds.length) {
+      setSelectedItemLength(selectedItemIds.length)
+    }
+  }, [selectedItemIds, setSelectedItemLength])
+
+  return (
+    <Box
+      sx={
+        !showMenu
+          ? {
+              // visually hides this label for sighted users
+              position: 'absolute',
+              width: '1px',
+              height: '1px',
+              padding: '0',
+              margin: '-1px',
+              overflow: 'hidden',
+              clip: 'rect(0, 0, 0, 0)',
+              whiteSpace: 'nowrap',
+              borderWidth: '0'
+            }
+          : {}
+      }
+    >
+      {loading ? (
+        <Box p={3} display="flex" justifyContent="center">
+          <Spinner />
+        </Box>
+      ) : (
+        <div ref={listContainerRef}>
+          {allItemsToRender.length ? (
+            <ActionList
+              selectionVariant="multiple"
+              // have to typecast to `ItemProps` because we have an extra property
+              // on `items` for Autocomplete: `metadata`
+              items={allItemsToRender as ItemProps[]}
+              role="listbox"
+              id={`${id}-listbox`}
+              aria-labelledby={ariaLabelledBy}
+            />
+          ) : (
+            <Box p={3}>{emptyStateText}</Box>
+          )}
+        </div>
+      )}
+    </Box>
+  )
+}
+
+AutocompleteMenu.defaultProps = {
+  emptyStateText: 'No selectable options',
+  selectionVariant: 'single'
+}
+
+AutocompleteMenu.displayName = 'AutocompleteMenu'
+
+export type AutocompleteMenuProps = ComponentProps<typeof AutocompleteMenu>
+export default AutocompleteMenu

package/src/Autocomplete/AutocompleteOverlay.tsx

@@ -0,0 +1,68 @@
+import React, {useCallback, useContext} from 'react'
+import {useAnchoredPosition} from '../hooks'
+import Overlay, {OverlayProps} from '../Overlay'
+import {ComponentProps} from '../utils/types'
+import {AutocompleteContext} from './AutocompleteContext'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
+
+type AutocompleteOverlayInternalProps = {
+  /**
+   * The ref of the element that the position of the menu is based on. By default, the menu is positioned based on the text input
+   */
+  menuAnchorRef?: React.RefObject<HTMLElement>
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Partial<OverlayProps>
+  children?: React.ReactNode
+} & Pick<React.AriaAttributes, 'aria-labelledby'> // TODO: consider making 'aria-labelledby' required
+
+function AutocompleteOverlay({menuAnchorRef, overlayProps, children}: AutocompleteOverlayInternalProps) {
+  const autocompleteContext = useContext(AutocompleteContext)
+  if (autocompleteContext === null) {
+    throw new Error('AutocompleteContext returned null values')
+  }
+  const {inputRef, scrollContainerRef, selectedItemLength, setShowMenu, showMenu = false} = autocompleteContext
+  const {floatingElementRef, position} = useAnchoredPosition(
+    {
+      side: 'outside-bottom',
+      align: 'start',
+      anchorElementRef: menuAnchorRef ? menuAnchorRef : inputRef
+    },
+    [showMenu, selectedItemLength]
+  )
+
+  const combinedOverlayRef = useCombinedRefs(scrollContainerRef, floatingElementRef)
+
+  const closeOptionList = useCallback(() => {
+    setShowMenu(false)
+  }, [setShowMenu])
+
+  if (typeof window === 'undefined') {
+    return null
+  }
+
+  return (
+    <Overlay
+      returnFocusRef={inputRef}
+      preventFocusOnOpen={true}
+      onClickOutside={closeOptionList}
+      onEscape={closeOptionList}
+      ref={combinedOverlayRef as React.RefObject<HTMLDivElement>}
+      top={position?.top}
+      left={position?.left}
+      visibility={showMenu ? 'visible' : 'hidden'}
+      sx={{
+        overflow: 'auto'
+      }}
+      {...overlayProps}
+    >
+      {children}
+    </Overlay>
+  )
+}
+
+AutocompleteOverlay.displayName = 'AutocompleteOverlay'
+
+export type AutocompleteOverlayProps = ComponentProps<typeof AutocompleteOverlay>
+export default AutocompleteOverlay

package/src/Autocomplete/index.ts

@@ -0,0 +1,2 @@
+export {default} from './Autocomplete'
+export type {AutocompleteMenuProps, AutocompleteInputProps, AutocompleteOverlayProps} from './Autocomplete'

package/src/Avatar.tsx

@@ -0,0 +1,44 @@
+import styled from 'styled-components'
+import {get} from './constants'
+import sx, {SxProp} from './sx'
+import {ComponentProps} from './utils/types'
+
+type StyledAvatarProps = {
+  /** Sets the width and height of the avatar. */
+  size?: number
+  /** Sets the shape of the avatar to a square if true. If false, the avatar will be circular. */
+  square?: boolean
+  /** URL of the avatar image. */
+  src: string
+  /** Provide alt text when the Avatar is used without the user's name next to it. */
+  alt?: string
+} & SxProp
+
+function getBorderRadius({size, square}: StyledAvatarProps) {
+  if (square) {
+    return size && size <= 24 ? '4px' : '6px'
+  } else {
+    return '50%'
+  }
+}
+
+const Avatar = styled.img.attrs<StyledAvatarProps>(props => ({
+  height: props.size,
+  width: props.size
+}))<StyledAvatarProps>`
+  display: inline-block;
+  overflow: hidden; // Ensure page layout in Firefox should images fail to load
+  line-height: ${get('lineHeights.condensedUltra')};
+  vertical-align: middle;
+  border-radius: ${props => getBorderRadius(props)};
+  ${sx}
+`
+
+Avatar.defaultProps = {
+  size: 20,
+  alt: '',
+  square: false
+}
+
+export type AvatarProps = ComponentProps<typeof Avatar>
+export default Avatar

package/src/AvatarPair.tsx

@@ -0,0 +1,35 @@
+import React from 'react'
+import styled from 'styled-components'
+import Avatar from './Avatar'
+import {get} from './constants'
+import {Box, BoxProps} from '.'
+
+const ChildAvatar = styled(Avatar)`
+  position: absolute;
+  right: -15%;
+  bottom: -9%;
+  box-shadow: ${get('shadows.avatar.childShadow')};
+`
+
+export type AvatarPairProps = BoxProps
+
+const AvatarPair = ({children, ...rest}: AvatarPairProps) => {
+  const avatars = React.Children.map(children, (child, i) => {
+    if (!React.isValidElement(child)) return child
+    return i === 0 ? (
+      React.cloneElement(child, {size: 40})
+    ) : (
+      <ChildAvatar bg="canvas.default" {...child.props} size={20} />
+    )
+  })
+  return (
+    <Box position="relative" display="inline-flex" {...rest}>
+      {avatars}
+    </Box>
+  )
+}
+
+// styled() changes this
+AvatarPair.displayName = 'AvatarPair'
+
+export default AvatarPair

package/src/AvatarStack.tsx

@@ -0,0 +1,159 @@
+import classnames from 'classnames'
+import React from 'react'
+import styled from 'styled-components'
+import {get} from './constants'
+import {Box} from '.'
+import sx, {SxProp} from './sx'
+
+type StyledAvatarStackWrapperProps = {
+  count?: number
+} & SxProp
+
+const AvatarStackWrapper = styled.span<StyledAvatarStackWrapperProps>`
+  display: flex;
+  position: relative;
+  height: 20px;
+  min-width: ${props => (props.count === 1 ? '20px' : props.count === 2 ? '30px' : '38px')};
+
+  .pc-AvatarItem {
+    flex-shrink: 0;
+    height: 20px;
+    width: 20px;
+    box-shadow: 0 0 0 1px ${get('colors.canvas.default')};
+    margin-left: -11px;
+    position: relative;
+    overflow: hidden;
+    transition: margin 0.2s ease-in-out, opacity 0.2s ease-in-out, visibility 0.2s ease-in-out,
+      box-shadow 0.1s ease-in-out;
+
+    &:first-child {
+      margin-left: 0;
+    }
+    &:nth-child(n + 4) {
+      display: none;
+    }
+  }
+
+  &.pc-AvatarStack--two {
+    min-width: 30px;
+    .pc-AvatarItem {
+      &:nth-child(n + 3) {
+        display: none;
+      }
+    }
+  }
+
+  &.pc-AvatarStack--three-plus {
+    min-width: 38px;
+    .pc-AvatarItem {
+      &:nth-child(3) {
+        opacity: ${100 - 3 * 15}%;
+        margin-left: -17px;
+      }
+      &:nth-child(4) {
+        opacity: ${100 - 4 * 15}%;
+        margin-left: -17px;
+      }
+      &:nth-child(5) {
+        opacity: ${100 - 5 * 15}%;
+        margin-left: -17px;
+      }
+      &:nth-child(n + 4) {
+        display: block;
+      }
+      &:nth-child(n + 6) {
+        opacity: 0;
+        visibility: hidden;
+      }
+    }
+  }
+
+  &.pc-AvatarStack--right {
+    justify-content: flex-end;
+    .pc-AvatarItem {
+      margin-left: 0 !important;
+      margin-right: -11px;
+
+      &:first-child {
+        margin-right: 0;
+      }
+    }
+
+    .pc-AvatarStackBody {
+      flex-direction: row-reverse;
+
+      &:hover {
+        .pc-AvatarItem {
+          margin-right: ${get('space.1')}!important;
+          margin-left: 0 !important;
+
+          &:first-child {
+            margin-right: 0 !important;
+          }
+        }
+      }
+    }
+  }
+
+  &.pc-AvatarStack--three-plus.pc-AvatarStack--right {
+    .pc-AvatarItem {
+      &:nth-child(3) {
+        margin-right: -17px;
+      }
+      &:nth-child(4) {
+        margin-right: -17px;
+      }
+      &:nth-child(5) {
+        margin-right: -17px;
+      }
+    }
+  }
+
+  .pc-AvatarStackBody:hover {
+    width: auto;
+
+    .pc-AvatarItem {
+      margin-left: ${get('space.1')};
+      opacity: 100%;
+      visibility: visible;
+      box-shadow: 0 0 0 4px ${get('colors.canvas.default')};
+      &:first-child {
+        margin-left: 0;
+      }
+    }
+  }
+
+  ${sx};
+`
+const transformChildren = (children: React.ReactNode) => {
+  return React.Children.map(children, (child, index) => {
+    if (!React.isValidElement(child)) return child
+    return React.cloneElement(child, {
+      className: classnames(child.props.className, 'pc-AvatarItem'),
+      sx: {zIndex: 10 - index, ...child.props.sx}
+    })
+  })
+}
+
+export type AvatarStackProps = {
+  alignRight?: boolean
+  children: React.ReactNode
+} & SxProp
+
+const AvatarStack = ({children, alignRight, sx: sxProp}: AvatarStackProps) => {
+  const count = React.Children.count(children)
+  const wrapperClassNames = classnames({
+    'pc-AvatarStack--two': count === 2,
+    'pc-AvatarStack--three-plus': count > 2,
+    'pc-AvatarStack--right': alignRight
+  })
+  return (
+    <AvatarStackWrapper count={count} className={wrapperClassNames} sx={sxProp}>
+      <Box position="absolute" display="flex" width="38px" className="pc-AvatarStackBody">
+        {transformChildren(children)}
+      </Box>
+    </AvatarStackWrapper>
+  )
+}
+
+export default AvatarStack

package/src/BaseStyles.tsx

@@ -0,0 +1,53 @@
+import React from 'react'
+import styled, {createGlobalStyle} from 'styled-components'
+import {COMMON, SystemCommonProps, SystemTypographyProps, TYPOGRAPHY} from './constants'
+import {ComponentProps} from './utils/types'
+
+const GlobalStyle = createGlobalStyle`
+  * { box-sizing: border-box; }
+  body { margin: 0; }
+  table { border-collapse: collapse; }
+  
+  [role="button"]:focus:not(:focus-visible):not(.focus-visible),
+  [role="tabpanel"][tabindex="0"]:focus:not(:focus-visible):not(.focus-visible),
+  button:focus:not(:focus-visible):not(.focus-visible),
+  summary:focus:not(:focus-visible):not(.focus-visible),
+  a:focus:not(:focus-visible):not(.focus-visible) {
+    outline: none;
+    box-shadow: none;
+  }
+
+  [tabindex="0"]:focus:not(:focus-visible):not(.focus-visible),
+  details-dialog:focus:not(:focus-visible):not(.focus-visible) {
+    outline: none;
+  }
+`
+
+const Base = styled.div<SystemTypographyProps & SystemCommonProps>`
+  ${TYPOGRAPHY};
+  ${COMMON};
+`
+
+export type BaseStylesProps = ComponentProps<typeof Base>
+
+function BaseStyles(props: BaseStylesProps) {
+  const {children, ...rest} = props
+
+  // load polyfill for :focus-visible
+  require('focus-visible')
+
+  return (
+    <Base {...rest} data-portal-root>
+      <GlobalStyle />
+      {children}
+    </Base>
+  )
+}
+
+BaseStyles.defaultProps = {
+  color: 'fg.default',
+  fontFamily: 'normal',
+  lineHeight: 'default'
+}
+
+export default BaseStyles