@primer/components 33.0.0 → 33.1.0-rc.6856bcf5

package/src/ActionMenu2.tsx

@@ -0,0 +1,116 @@
+import Button, {ButtonProps} from './Button'
+import React from 'react'
+import {AnchoredOverlay, AnchoredOverlayProps} from './AnchoredOverlay'
+import {OverlayProps} from './Overlay'
+import {useProvidedRefOrCreate, useProvidedStateOrCreate} from './hooks'
+import {Divider} from './ActionList2/Divider'
+import {ActionListContainerContext} from './ActionList2/ActionListContainerContext'
+import {MandateProps} from './utils/types'
+
+type MenuContextProps = Pick<AnchoredOverlayProps, 'anchorRef' | 'renderAnchor' | 'open' | 'onOpen' | 'onClose'>
+export const MenuContext = React.createContext<MenuContextProps>({renderAnchor: null, open: false})
+
+export type ActionMenuProps = {
+  /**
+   * Recommended: `ActionMenu.Button` or `ActionMenu.Anchor` with `ActionMenu.Overlay`
+   */
+  children: React.ReactElement[] | React.ReactElement
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `onOpenChange`.
+   */
+  open?: boolean
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.
+   */
+  onOpenChange?: (s: boolean) => void
+} & Pick<AnchoredOverlayProps, 'anchorRef'>
+
+const Menu: React.FC<ActionMenuProps> = ({
+  anchorRef: externalAnchorRef,
+  open,
+  onOpenChange,
+  children
+}: ActionMenuProps) => {
+  const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, onOpenChange, false)
+  const onOpen = React.useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
+  const onClose = React.useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
+
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  let renderAnchor: AnchoredOverlayProps['renderAnchor'] = null
+
+  // 🚨 Hack for good API!
+  // we strip out Anchor from children and pass it to AnchoredOverlay to render
+  // with additional props for accessibility
+  const contents = React.Children.map(children, child => {
+    if (child.type === MenuButton || child.type === Anchor) {
+      renderAnchor = anchorProps => React.cloneElement(child, anchorProps)
+      return null
+    }
+    return child
+  })
+
+  return (
+    <MenuContext.Provider value={{anchorRef, renderAnchor, open: combinedOpenState, onOpen, onClose}}>
+      {contents}
+    </MenuContext.Provider>
+  )
+}
+
+export type MenuAnchorProps = {children: React.ReactElement}
+const Anchor = React.forwardRef<AnchoredOverlayProps['anchorRef'], MenuAnchorProps>(
+  ({children, ...anchorProps}, anchorRef) => {
+    return React.cloneElement(children, {...anchorProps, ref: anchorRef})
+  }
+)
+
+/** this component is syntactical sugar 🍭 */
+export type MenuButtonProps = ButtonProps
+const MenuButton = React.forwardRef<AnchoredOverlayProps['anchorRef'], ButtonProps>((props, anchorRef) => {
+  return (
+    <Anchor ref={anchorRef}>
+      <Button {...props} />
+    </Anchor>
+  )
+})
+
+type MenuOverlayProps = Partial<OverlayProps> & {
+  /**
+   * Recommended: `ActionList`
+   */
+  children: React.ReactElement[] | React.ReactElement
+}
+const Overlay: React.FC<MenuOverlayProps> = ({children, ...overlayProps}) => {
+  // we typecast anchorRef as required instead of optional
+  // because we know that we're setting it in context in Menu
+  const {anchorRef, renderAnchor, open, onOpen, onClose} = React.useContext(MenuContext) as MandateProps<
+    MenuContextProps,
+    'anchorRef'
+  >
+
+  return (
+    <AnchoredOverlay
+      anchorRef={anchorRef}
+      renderAnchor={renderAnchor}
+      open={open}
+      onOpen={onOpen}
+      onClose={onClose}
+      overlayProps={overlayProps}
+    >
+      <ActionListContainerContext.Provider
+        value={{
+          container: 'ActionMenu',
+          listRole: 'menu',
+          itemRole: 'menuitem',
+          afterSelect: onClose
+        }}
+      >
+        {children}
+      </ActionListContainerContext.Provider>
+    </AnchoredOverlay>
+  )
+}
+
+Menu.displayName = 'ActionMenu'
+export const ActionMenu = Object.assign(Menu, {Button: MenuButton, Anchor, Overlay, Divider})

package/src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -0,0 +1,191 @@
+import React, {useCallback, useEffect} from 'react'
+import Overlay, {OverlayProps} from '../Overlay'
+import {FocusTrapHookSettings, useFocusTrap} from '../hooks/useFocusTrap'
+import {FocusZoneHookSettings, useFocusZone} from '../hooks/useFocusZone'
+import {useAnchoredPosition, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
+import {useSSRSafeId} from '@react-aria/ssr'
+import {PositionSettings} from '../behaviors/anchoredPosition'
+
+interface AnchoredOverlayPropsWithAnchor {
+  /**
+   * A custom function component used to render the anchor element.
+   * Will receive the selected text as `children` prop when an item is activated.
+   */
+  renderAnchor: <T extends React.HTMLAttributes<HTMLElement>>(props: T) => JSX.Element
+
+  /**
+   * An override to the internal ref that will be spread on to the renderAnchor
+   */
+  anchorRef?: React.RefObject<HTMLElement>
+}
+
+interface AnchoredOverlayPropsWithoutAnchor {
+  /**
+   * A custom function component used to render the anchor element.
+   * When renderAnchor is null, an anchorRef is required.
+   */
+  renderAnchor: null
+
+  /**
+   * An override to the internal renderAnchor ref that will be used to position the overlay.
+   * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
+   */
+  anchorRef: React.RefObject<HTMLElement>
+}
+
+export type AnchoredOverlayWrapperAnchorProps =
+  | Partial<AnchoredOverlayPropsWithAnchor>
+  | AnchoredOverlayPropsWithoutAnchor
+
+interface AnchoredOverlayBaseProps extends Pick<OverlayProps, 'height' | 'width'> {
+  /**
+   * Determines whether the overlay portion of the component should be shown or not
+   */
+  open: boolean
+
+  /**
+   * A callback which is called whenever the overlay is currently closed and an "open gesture" is detected.
+   */
+  onOpen?: (gesture: 'anchor-click' | 'anchor-key-press') => unknown
+
+  /**
+   * A callback which is called whenever the overlay is currently open and a "close gesture" is detected.
+   */
+  onClose?: (gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown
+
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Partial<OverlayProps>
+
+  /**
+   * Settings to apply to the Focus Zone on the internal `Overlay` component.
+   */
+  focusTrapSettings?: Partial<FocusTrapHookSettings>
+
+  /**
+   * Settings to apply to the Focus Zone on the internal `Overlay` component.
+   */
+  focusZoneSettings?: Partial<FocusZoneHookSettings>
+}
+
+export type AnchoredOverlayProps = AnchoredOverlayBaseProps &
+  (AnchoredOverlayPropsWithAnchor | AnchoredOverlayPropsWithoutAnchor) &
+  Partial<Pick<PositionSettings, 'align' | 'side'>>
+
+/**
+ * An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
+ * The overlay can be opened and navigated using keyboard or mouse.
+ */
+export const AnchoredOverlay: React.FC<AnchoredOverlayProps> = ({
+  renderAnchor,
+  anchorRef: externalAnchorRef,
+  children,
+  open,
+  onOpen,
+  onClose,
+  height,
+  width,
+  overlayProps,
+  focusTrapSettings,
+  focusZoneSettings,
+  side,
+  align
+}) => {
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
+  const anchorId = useSSRSafeId()
+
+  const onClickOutside = useCallback(() => onClose?.('click-outside'), [onClose])
+  const onEscape = useCallback(() => onClose?.('escape'), [onClose])
+
+  const onAnchorKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
+      if (!event.defaultPrevented) {
+        if (!open && ['ArrowDown', 'ArrowUp', ' ', 'Enter'].includes(event.key)) {
+          onOpen?.('anchor-key-press')
+          event.preventDefault()
+        }
+      }
+    },
+    [open, onOpen]
+  )
+  const onAnchorClick = useCallback(
+    (event: React.MouseEvent<HTMLElement>) => {
+      if (event.defaultPrevented || event.button !== 0) {
+        return
+      }
+      if (!open) {
+        onOpen?.('anchor-click')
+      } else {
+        onClose?.('anchor-click')
+      }
+    },
+    [open, onOpen, onClose]
+  )
+
+  const {position} = useAnchoredPosition(
+    {
+      anchorElementRef: anchorRef,
+      floatingElementRef: overlayRef,
+      side,
+      align
+    },
+    [overlayRef.current]
+  )
+
+  useEffect(() => {
+    // ensure overlay ref gets cleared when closed, so position can reset between closing/re-opening
+    if (!open && overlayRef.current) {
+      updateOverlayRef(null)
+    }
+  }, [open, overlayRef, updateOverlayRef])
+
+  useFocusZone({
+    containerRef: overlayRef,
+    disabled: !open || !position,
+    ...focusZoneSettings
+  })
+  useFocusTrap({containerRef: overlayRef, disabled: !open || !position, ...focusTrapSettings})
+
+  return (
+    <>
+      {renderAnchor &&
+        renderAnchor({
+          ref: anchorRef,
+          id: anchorId,
+          'aria-labelledby': anchorId,
+          'aria-haspopup': 'true',
+          tabIndex: 0,
+          onClick: onAnchorClick,
+          onKeyDown: onAnchorKeyDown
+        })}
+      {open ? (
+        <Overlay
+          returnFocusRef={anchorRef}
+          onClickOutside={onClickOutside}
+          ignoreClickRefs={[anchorRef]}
+          onEscape={onEscape}
+          ref={updateOverlayRef}
+          role="none"
+          visibility={position ? 'visible' : 'hidden'}
+          height={height}
+          width={width}
+          top={position?.top || 0}
+          left={position?.left || 0}
+          anchorSide={position?.anchorSide}
+          {...overlayProps}
+        >
+          {children}
+        </Overlay>
+      ) : null}
+    </>
+  )
+}
+
+AnchoredOverlay.displayName = 'AnchoredOverlay'
+
+AnchoredOverlay.defaultProps = {
+  side: 'outside-bottom',
+  align: 'start'
+}

package/src/AnchoredOverlay/index.ts

@@ -0,0 +1,2 @@
+export {AnchoredOverlay} from './AnchoredOverlay'
+export type {AnchoredOverlayProps} from './AnchoredOverlay'

package/src/Autocomplete/Autocomplete.tsx

@@ -0,0 +1,103 @@
+import React, {useCallback, useReducer, useRef} from 'react'
+import {useSSRSafeId} from '@react-aria/ssr'
+import {ComponentProps} from '../utils/types'
+import {AutocompleteContext} from './AutocompleteContext'
+import AutocompleteInput from './AutocompleteInput'
+import AutocompleteMenu from './AutocompleteMenu'
+import AutocompleteOverlay from './AutocompleteOverlay'
+
+type Action =
+  | {type: 'showMenu' | 'isMenuDirectlyActivated'; payload: boolean}
+  | {type: 'autocompleteSuggestion' | 'inputValue'; payload: string}
+  | {type: 'selectedItemLength'; payload: number}
+
+interface State {
+  inputValue: string
+  showMenu: boolean
+  isMenuDirectlyActivated: boolean
+  autocompleteSuggestion: string
+  selectedItemLength: number
+}
+
+const initialState = {
+  inputValue: '',
+  showMenu: false,
+  isMenuDirectlyActivated: false,
+  autocompleteSuggestion: '',
+  selectedItemLength: 0
+}
+
+const reducer = (state: State, action: Action) => {
+  const {type, payload} = action
+  switch (type) {
+    case 'inputValue':
+      return {...state, inputValue: payload as State['inputValue']}
+    case 'showMenu':
+      return {...state, showMenu: payload as State['showMenu']}
+    case 'isMenuDirectlyActivated':
+      return {...state, isMenuDirectlyActivated: payload as State['isMenuDirectlyActivated']}
+    case 'autocompleteSuggestion':
+      return {...state, autocompleteSuggestion: payload as State['autocompleteSuggestion']}
+    case 'selectedItemLength':
+      return {...state, selectedItemLength: payload as State['selectedItemLength']}
+    default:
+      return state
+  }
+}
+
+const Autocomplete: React.FC<{id?: string}> = ({children, id: idProp}) => {
+  const activeDescendantRef = useRef<HTMLElement>(null)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [state, dispatch] = useReducer(reducer, initialState)
+  const {inputValue, showMenu, autocompleteSuggestion, isMenuDirectlyActivated, selectedItemLength} = state
+  const setInputValue = useCallback((value: State['inputValue']) => {
+    dispatch({type: 'inputValue', payload: value})
+  }, [])
+  const setShowMenu = useCallback((value: State['showMenu']) => {
+    dispatch({type: 'showMenu', payload: value})
+  }, [])
+  const setAutocompleteSuggestion = useCallback((value: State['autocompleteSuggestion']) => {
+    dispatch({type: 'autocompleteSuggestion', payload: value})
+  }, [])
+  const setIsMenuDirectlyActivated = useCallback((value: State['isMenuDirectlyActivated']) => {
+    dispatch({type: 'isMenuDirectlyActivated', payload: value})
+  }, [])
+  const setSelectedItemLength = useCallback((value: State['selectedItemLength']) => {
+    dispatch({type: 'selectedItemLength', payload: value})
+  }, [])
+  const id = useSSRSafeId(idProp)
+
+  return (
+    <AutocompleteContext.Provider
+      value={{
+        activeDescendantRef,
+        autocompleteSuggestion,
+        id,
+        inputRef,
+        inputValue,
+        isMenuDirectlyActivated,
+        scrollContainerRef,
+        selectedItemLength,
+        setAutocompleteSuggestion,
+        setInputValue,
+        setIsMenuDirectlyActivated,
+        setShowMenu,
+        setSelectedItemLength,
+        showMenu
+      }}
+    >
+      {children}
+    </AutocompleteContext.Provider>
+  )
+}
+
+export type AutocompleteProps = ComponentProps<typeof Autocomplete>
+export type {AutocompleteInputProps} from './AutocompleteInput'
+export type {AutocompleteMenuProps} from './AutocompleteMenu'
+export type {AutocompleteOverlayProps} from './AutocompleteOverlay'
+export default Object.assign(Autocomplete, {
+  Input: AutocompleteInput,
+  Menu: AutocompleteMenu,
+  Overlay: AutocompleteOverlay
+})

package/src/Autocomplete/AutocompleteContext.tsx

@@ -0,0 +1,19 @@
+import {createContext} from 'react'
+
+export const AutocompleteContext = createContext<{
+  activeDescendantRef: React.MutableRefObject<HTMLElement | null>
+  autocompleteSuggestion: string
+  // TODO: consider changing `id` to `listboxId` because we're just using it to associate the input and combobox with the listbox
+  id: string
+  inputRef: React.MutableRefObject<HTMLInputElement | null>
+  inputValue: string
+  isMenuDirectlyActivated: boolean
+  scrollContainerRef: React.MutableRefObject<HTMLElement | null>
+  selectedItemLength: number
+  setAutocompleteSuggestion: (value: string) => void
+  setInputValue: (value: string) => void
+  setIsMenuDirectlyActivated: (value: boolean) => void
+  setSelectedItemLength: (value: number) => void
+  setShowMenu: (value: boolean) => void
+  showMenu: boolean
+} | null>(null)

package/src/Autocomplete/AutocompleteInput.tsx

@@ -0,0 +1,179 @@
+import React, {
+  ChangeEventHandler,
+  FocusEventHandler,
+  KeyboardEventHandler,
+  MutableRefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useState
+} from 'react'
+import {ForwardRefComponent as PolymorphicForwardRefComponent} from '@radix-ui/react-polymorphic'
+import {AutocompleteContext} from './AutocompleteContext'
+import TextInput from '../TextInput'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
+import {ComponentProps} from '../utils/types'
+
+type InternalAutocompleteInputProps = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  as?: React.ComponentType<any>
+}
+
+const AutocompleteInput = React.forwardRef(
+  (
+    {as: Component = TextInput, onFocus, onBlur, onChange, onKeyDown, onKeyUp, onKeyPress, value, ...props},
+    forwardedRef
+  ) => {
+    const autocompleteContext = useContext(AutocompleteContext)
+    if (autocompleteContext === null) {
+      throw new Error('AutocompleteContext returned null values')
+    }
+    const {
+      activeDescendantRef,
+      autocompleteSuggestion = '',
+      id,
+      inputRef,
+      inputValue = '',
+      isMenuDirectlyActivated,
+      setInputValue,
+      setShowMenu,
+      showMenu
+    } = autocompleteContext
+    const combinedInputRef = useCombinedRefs(inputRef, forwardedRef)
+    const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
+
+    const handleInputFocus: FocusEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onFocus && onFocus(event)
+        setShowMenu(true)
+      },
+      [onFocus, setShowMenu]
+    )
+
+    const handleInputBlur: FocusEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onBlur && onBlur(event)
+
+        // HACK: wait a tick and check the focused element before hiding the autocomplete menu
+        // this prevents the menu from hiding when the user is clicking an option in the Autoselect.Menu,
+        // but still hides the menu when the user blurs the input by tabbing out or clicking somewhere else on the page
+        setTimeout(() => {
+          if (document.activeElement !== combinedInputRef.current) {
+            setShowMenu(false)
+          }
+        }, 0)
+      },
+      [onBlur, setShowMenu, combinedInputRef]
+    )
+
+    const handleInputChange: ChangeEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onChange && onChange(event)
+        setInputValue(event.currentTarget.value)
+        if (!showMenu) {
+          setShowMenu(true)
+        }
+      },
+      [onChange, setInputValue, setShowMenu, showMenu]
+    )
+
+    const handleInputKeyDown: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyDown && onKeyDown(event)
+
+        if (event.key === 'Backspace') {
+          setHighlightRemainingText(false)
+        }
+
+        if (event.key === 'Escape' && inputRef.current?.value) {
+          setInputValue('')
+          inputRef.current.value = ''
+        }
+      },
+      [inputRef, setInputValue, setHighlightRemainingText, onKeyDown]
+    )
+
+    const handleInputKeyUp: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyUp && onKeyUp(event)
+
+        if (event.key === 'Backspace') {
+          setHighlightRemainingText(true)
+        }
+      },
+      [setHighlightRemainingText, onKeyUp]
+    )
+
+    const onInputKeyPress: KeyboardEventHandler<HTMLInputElement> = useCallback(
+      event => {
+        onKeyPress && onKeyPress(event)
+
+        if (showMenu && event.key === 'Enter' && activeDescendantRef.current) {
+          event.preventDefault()
+          event.nativeEvent.stopImmediatePropagation()
+
+          // Forward Enter key press to active descendant so that item gets activated
+          const activeDescendantEvent = new KeyboardEvent(event.type, event.nativeEvent)
+          activeDescendantRef.current.dispatchEvent(activeDescendantEvent)
+        }
+      },
+      [activeDescendantRef, showMenu, onKeyPress]
+    )
+
+    useEffect(() => {
+      if (!inputRef.current) {
+        return
+      }
+
+      // resets input value to being empty after a selection has been made
+      if (!autocompleteSuggestion) {
+        inputRef.current.value = inputValue
+      }
+
+      // TODO: fix bug where this function prevents `onChange` from being triggered if the highlighted item text
+      //       is the same as what I'm typing
+      //       e.g.: typing 'tw' highights 'two', but when I 'two', the text input change does not get triggered
+      if (highlightRemainingText && autocompleteSuggestion && (inputValue || isMenuDirectlyActivated)) {
+        inputRef.current.value = autocompleteSuggestion
+
+        if (autocompleteSuggestion.toLowerCase().indexOf(inputValue.toLowerCase()) === 0) {
+          inputRef.current.setSelectionRange(inputValue.length, autocompleteSuggestion.length)
+        }
+      }
+
+      // calling this useEffeect when `highlightRemainingText` changes breaks backspace functionality
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [autocompleteSuggestion, inputValue, inputRef, isMenuDirectlyActivated])
+
+    useEffect(() => {
+      if (value) {
+        setInputValue(value.toString())
+      }
+    }, [value, setInputValue])
+
+    return (
+      <Component
+        onFocus={handleInputFocus}
+        onBlur={handleInputBlur}
+        onChange={handleInputChange}
+        onKeyDown={handleInputKeyDown}
+        onKeyPress={onInputKeyPress}
+        onKeyUp={handleInputKeyUp}
+        ref={combinedInputRef as MutableRefObject<HTMLInputElement>}
+        aria-controls={`${id}-listbox`}
+        aria-autocomplete="both"
+        role="combobox"
+        aria-expanded={showMenu}
+        aria-haspopup="listbox"
+        aria-owns={`${id}-listbox`}
+        autocomplete="off"
+        {...props}
+      />
+    )
+  }
+) as PolymorphicForwardRefComponent<typeof TextInput, InternalAutocompleteInputProps>
+
+AutocompleteInput.displayName = 'AutocompleteInput'
+
+export type AutocompleteInputProps = ComponentProps<typeof AutocompleteInput>
+export default AutocompleteInput