@primer/components 29.1.0-rc.79e8b21e → 29.1.0

package/src/constants.ts

@@ -1,62 +0,0 @@
-import {themeGet} from '@styled-system/theme-get'
-// eslint-disable-next-line import/no-namespace
-import * as styledSystem from 'styled-system'
-import theme from './theme'
-
-const {get: getKey, compose, system} = styledSystem
-
-export const get = (key: string) => themeGet(key, getKey(theme, key))
-
-// Common props
-
-export const COMMON = compose(styledSystem.space, styledSystem.color, styledSystem.display)
-
-export interface SystemCommonProps
-  extends styledSystem.ColorProps,
-    styledSystem.SpaceProps,
-    styledSystem.DisplayProps {}
-
-// Typography props
-
-const whiteSpace = system({
-  whiteSpace: {
-    property: 'whiteSpace'
-    // cssProperty: 'whiteSpace',
-  }
-})
-
-export const TYPOGRAPHY = compose(styledSystem.typography, whiteSpace)
-
-export interface SystemTypographyProps extends styledSystem.TypographyProps {
-  whiteSpace?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line'
-}
-
-// Border props
-
-export const BORDER = compose(styledSystem.border, styledSystem.shadow)
-
-export interface SystemBorderProps extends styledSystem.BorderProps, styledSystem.ShadowProps {}
-
-// Layout props
-
-export const LAYOUT = styledSystem.layout
-
-export type SystemLayoutProps = styledSystem.LayoutProps
-
-// Position props
-
-export const POSITION = styledSystem.position
-
-export type SystemPositionProps = styledSystem.PositionProps
-
-// Flex props
-
-export const FLEX = styledSystem.flexbox
-
-export type SystemFlexProps = styledSystem.FlexboxProps
-
-// Grid props
-
-export const GRID = styledSystem.grid
-
-export type SystemGridProps = styledSystem.GridProps

package/src/hooks/index.ts

@@ -1,11 +0,0 @@
-export {useOnOutsideClick} from './useOnOutsideClick'
-export type {UseOnOutsideClickSettings, TouchOrMouseEvent} from './useOnOutsideClick'
-export {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
-export {useOnEscapePress} from './useOnEscapePress'
-export {useOpenAndCloseFocus} from './useOpenAndCloseFocus'
-export type {UseOpenAndCloseFocusSettings} from './useOpenAndCloseFocus'
-export type {AnchoredPositionHookSettings} from './useAnchoredPosition'
-export {useAnchoredPosition} from './useAnchoredPosition'
-export {useOverlay} from './useOverlay'
-export type {UseOverlaySettings} from './useOverlay'
-export {useRenderForcingRef} from './useRenderForcingRef'

package/src/hooks/useAnchoredPosition.ts

@@ -1,53 +0,0 @@
-import React from 'react'
-import {PositionSettings, getAnchoredPosition, AnchorPosition} from '../behaviors/anchoredPosition'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
-import {useResizeObserver} from './useResizeObserver'
-
-export interface AnchoredPositionHookSettings extends Partial<PositionSettings> {
-  floatingElementRef?: React.RefObject<Element>
-  anchorElementRef?: React.RefObject<Element>
-}
-
-/**
- * Calculates the top and left values for an absolutely-positioned floating element
- * to be anchored to some anchor element. Returns refs for the floating element
- * and the anchor element, along with the position.
- * @param settings Settings for calculating the anchored position.
- * @param dependencies Dependencies to determine when to re-calculate the position.
- * @returns An object of {top: number, left: number} to absolutely-position the
- * floating element.
- */
-export function useAnchoredPosition(
-  settings?: AnchoredPositionHookSettings,
-  dependencies: React.DependencyList = []
-): {
-  floatingElementRef: React.RefObject<Element>
-  anchorElementRef: React.RefObject<Element>
-  position: AnchorPosition | undefined
-} {
-  const floatingElementRef = useProvidedRefOrCreate(settings?.floatingElementRef)
-  const anchorElementRef = useProvidedRefOrCreate(settings?.anchorElementRef)
-  const [position, setPosition] = React.useState<AnchorPosition | undefined>(undefined)
-
-  const updatePosition = React.useCallback(
-    () => {
-      if (floatingElementRef.current instanceof Element && anchorElementRef.current instanceof Element) {
-        setPosition(getAnchoredPosition(floatingElementRef.current, anchorElementRef.current, settings))
-      } else {
-        setPosition(undefined)
-      }
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [floatingElementRef, anchorElementRef, ...dependencies]
-  )
-
-  React.useLayoutEffect(updatePosition, [updatePosition])
-
-  useResizeObserver(updatePosition)
-
-  return {
-    floatingElementRef,
-    anchorElementRef,
-    position
-  }
-}

package/src/hooks/useCombinedRefs.ts

@@ -1,40 +0,0 @@
-import React, {ForwardedRef, useRef} from 'react'
-
-/**
- * Creates a ref by combining multiple constituent refs. The ref returned by this hook
- * should be passed as the ref for the element that needs to be shared. This is
- * particularly useful when you are using `React.forwardRef` in your component but you
- * also want to be able to access the local element. This is a small anti-pattern,
- * though, as it breaks encapsulation.
- * @param refs
- */
-export function useCombinedRefs<T>(...refs: (ForwardedRef<T> | null | undefined)[]) {
-  const combinedRef = useRef<T | null>(null)
-
-  React.useLayoutEffect(() => {
-    function setRefs(current: T | null = null) {
-      for (const ref of refs) {
-        if (!ref) {
-          return
-        }
-        if (typeof ref === 'function') {
-          ref(current)
-        } else {
-          ref.current = current
-        }
-      }
-    }
-
-    setRefs(combinedRef.current)
-
-    return () => {
-      // ensure the refs get updated on unmount
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      setRefs(combinedRef.current)
-    }
-
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [...refs, combinedRef.current])
-
-  return combinedRef
-}

package/src/hooks/useDetails.tsx

@@ -1,54 +0,0 @@
-import {useCallback, useEffect, useState, useRef} from 'react'
-
-type UseDetailsParameters = {
-  ref?: React.RefObject<HTMLElement>
-  closeOnOutsideClick?: boolean
-  defaultOpen?: boolean
-  onClickOutside?: (event: MouseEvent) => void
-}
-
-function useDetails({ref, closeOnOutsideClick, defaultOpen, onClickOutside}: UseDetailsParameters) {
-  const [open, setOpen] = useState(defaultOpen)
-  const backupRef = useRef(null)
-  const customRef = ref ?? backupRef
-
-  const onClickOutsideInternal = useCallback(
-    (event: MouseEvent) => {
-      const {current} = customRef
-      const eventTarget = event.target as HTMLElement
-      const closest = eventTarget.closest('details') as HTMLDetailsElement
-      if (closest !== current) {
-        onClickOutside && onClickOutside(event)
-        if (!event.defaultPrevented) {
-          setOpen(false)
-        }
-      }
-    },
-    [customRef, setOpen, onClickOutside]
-  )
-
-  // handles the overlay behavior - closing the menu when clicking outside of it
-  useEffect(() => {
-    if (open && closeOnOutsideClick) {
-      document.addEventListener('click', onClickOutsideInternal)
-      return () => {
-        document.removeEventListener('click', onClickOutsideInternal)
-      }
-    }
-  }, [open, closeOnOutsideClick, onClickOutsideInternal])
-
-  const handleToggle = (e: React.SyntheticEvent<HTMLElement, Event>) => {
-    if (!e.defaultPrevented) {
-      const eventTarget = e.target as HTMLDetailsElement
-      setOpen(eventTarget.open)
-    }
-  }
-
-  const getDetailsProps = () => {
-    return {onToggle: handleToggle, open, ref: customRef}
-  }
-
-  return {open, setOpen, getDetailsProps}
-}
-
-export default useDetails

package/src/hooks/useDialog.ts

@@ -1,121 +0,0 @@
-import {useCallback, useEffect} from 'react'
-
-const noop = () => null
-
-function visible(el: HTMLInputElement) {
-  return !el.hidden && (!el.type || el.type !== 'hidden') && (el.offsetWidth > 0 || el.offsetHeight > 0)
-}
-
-function focusable(el: Element) {
-  const inputEl = el as HTMLInputElement
-  return inputEl.tabIndex >= 0 && !inputEl.disabled && visible(inputEl)
-}
-
-type UseDialogParameters = {
-  modalRef: React.RefObject<HTMLElement>
-  overlayRef: React.RefObject<HTMLElement>
-  isOpen?: boolean
-  onDismiss?: () => void
-  initialFocusRef?: React.RefObject<HTMLElement>
-  closeButtonRef?: React.RefObject<HTMLElement>
-  returnFocusRef?: React.RefObject<HTMLElement>
-}
-
-function useDialog({
-  modalRef,
-  overlayRef,
-  isOpen,
-  onDismiss = noop,
-  initialFocusRef,
-  closeButtonRef
-}: UseDialogParameters) {
-  const onClickOutside = useCallback(
-    e => {
-      if (
-        modalRef.current &&
-        overlayRef.current &&
-        !modalRef.current.contains(e.target) &&
-        overlayRef.current.contains(e.target)
-      ) {
-        onDismiss()
-      }
-    },
-    [onDismiss, modalRef, overlayRef]
-  )
-
-  useEffect(() => {
-    if (isOpen) {
-      document.addEventListener('click', onClickOutside)
-      return () => {
-        document.removeEventListener('click', onClickOutside)
-      }
-    }
-  }, [isOpen, onClickOutside])
-
-  useEffect(() => {
-    if (isOpen) {
-      if (initialFocusRef && initialFocusRef.current) {
-        initialFocusRef.current.focus()
-      } else if (closeButtonRef && closeButtonRef.current) {
-        closeButtonRef.current.focus()
-      }
-    }
-  }, [isOpen, initialFocusRef, closeButtonRef])
-
-  const getFocusableItem = useCallback(
-    (e: Event, movement: number) => {
-      if (modalRef.current) {
-        const items = Array.from(modalRef.current.querySelectorAll('*')).filter(focusable)
-        if (items.length === 0) return
-        e.preventDefault()
-        const focusedElement = document.activeElement
-        if (!focusedElement) {
-          return
-        }
-
-        const index = items.indexOf(focusedElement)
-        const offsetIndex = index + movement
-        const fallbackIndex = movement === 1 ? 0 : items.length - 1
-        const focusableItem = items[offsetIndex] || items[fallbackIndex]
-        return focusableItem as HTMLElement
-      }
-    },
-    [modalRef]
-  )
-
-  const handleTab = useCallback(
-    e => {
-      const movement = e.shiftKey ? -1 : 1
-      const focusableItem = getFocusableItem(e, movement)
-      if (!focusableItem) {
-        return
-      }
-
-      focusableItem.focus()
-    },
-    [getFocusableItem]
-  )
-
-  const onKeyDown = useCallback(
-    event => {
-      switch (event.key) {
-        case 'Tab':
-          handleTab(event)
-          break
-        case 'Escape':
-          onDismiss()
-          event.stopPropagation()
-          break
-      }
-    },
-    [handleTab, onDismiss]
-  )
-
-  const getDialogProps = () => {
-    return {onKeyDown}
-  }
-
-  return {getDialogProps}
-}
-
-export default useDialog

package/src/hooks/useFocusTrap.ts

@@ -1,80 +0,0 @@
-import React from 'react'
-import {focusTrap} from '../behaviors/focusTrap'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
-
-export interface FocusTrapHookSettings {
-  /**
-   * Ref that will be used for the trapping container. If not provided, one will
-   * be created by this hook and returned.
-   */
-  containerRef?: React.RefObject<HTMLElement>
-
-  /**
-   * Ref for the element that should receive focus when the focus trap is first enabled. If
-   * not provided, one will be created by this hook and returned. Its use is optional.
-   */
-  initialFocusRef?: React.RefObject<HTMLElement>
-
-  /**
-   * Set to true to disable the focus trap and clean up listeners. Can be re-enabled at
-   * any time.
-   */
-  disabled?: boolean
-
-  /**
-   * If true, when this focus trap is cleaned up, restore focus to the element that had
-   * focus immediately before the focus trap was enabled. (Default: false)
-   */
-  restoreFocusOnCleanUp?: boolean
-}
-
-/**
- * Hook used to trap focus inside a container. Returns a ref that can be added to the container
- * that should trap focus.
- * @param settings {FocusTrapHookSettings}
- */
-export function useFocusTrap(
-  settings?: FocusTrapHookSettings,
-  dependencies: React.DependencyList = []
-): {containerRef: React.RefObject<HTMLElement>; initialFocusRef: React.RefObject<HTMLElement>} {
-  const containerRef = useProvidedRefOrCreate(settings?.containerRef)
-  const initialFocusRef = useProvidedRefOrCreate(settings?.initialFocusRef)
-  const disabled = settings?.disabled
-  const abortController = React.useRef<AbortController>()
-  const previousFocusedElement = React.useRef<Element | null>(null)
-
-  // If we are enabling a focus trap and haven't already stored the previously focused element
-  // go ahead an do that so we can restore later when the trap is disabled.
-  if (!previousFocusedElement.current && !settings?.disabled) {
-    previousFocusedElement.current = document.activeElement
-  }
-
-  // This function removes the event listeners that enable the focus trap and restores focus
-  // to the previously-focused element (if necessary).
-  function disableTrap() {
-    abortController.current?.abort()
-    if (settings?.restoreFocusOnCleanUp && previousFocusedElement.current instanceof HTMLElement) {
-      previousFocusedElement.current.focus()
-      previousFocusedElement.current = null
-    }
-  }
-
-  React.useEffect(
-    () => {
-      if (containerRef.current instanceof HTMLElement) {
-        if (!disabled) {
-          abortController.current = focusTrap(containerRef.current, initialFocusRef.current ?? undefined)
-          return () => {
-            disableTrap()
-          }
-        } else {
-          disableTrap()
-        }
-      }
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [containerRef, initialFocusRef, disabled, ...dependencies]
-  )
-
-  return {containerRef, initialFocusRef}
-}

package/src/hooks/useFocusZone.ts

@@ -1,64 +0,0 @@
-import React, {useEffect} from 'react'
-import {focusZone, FocusZoneSettings} from '../behaviors/focusZone'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
-
-export interface FocusZoneHookSettings extends Omit<FocusZoneSettings, 'activeDescendantControl'> {
-  /**
-   * Optional ref for the container that holds all elements participating in arrow key focus.
-   * If one is not passed, we will create one for you and return it from the hook.
-   */
-  containerRef?: React.RefObject<HTMLElement>
-
-  /**
-   * If using the "active descendant" focus pattern, pass `true` or a ref to the controlling
-   * element. If a ref object is not passed, we will create one for you.
-   */
-  activeDescendantFocus?: boolean | React.RefObject<HTMLElement>
-
-  /**
-   * Set to true to disable the focus zone and clean up listeners. Can be re-enabled at
-   * any time.
-   */
-  disabled?: boolean
-}
-
-export function useFocusZone(
-  settings: FocusZoneHookSettings = {},
-  dependencies: React.DependencyList = []
-): {containerRef: React.RefObject<HTMLElement>; activeDescendantControlRef: React.RefObject<HTMLElement>} {
-  const containerRef = useProvidedRefOrCreate(settings.containerRef)
-  const useActiveDescendant = !!settings.activeDescendantFocus
-  const passedActiveDescendantRef =
-    typeof settings.activeDescendantFocus === 'boolean' || !settings.activeDescendantFocus
-      ? undefined
-      : settings.activeDescendantFocus
-  const activeDescendantControlRef = useProvidedRefOrCreate(passedActiveDescendantRef)
-  const disabled = settings.disabled
-  const abortController = React.useRef<AbortController>()
-
-  useEffect(
-    () => {
-      if (
-        containerRef.current instanceof HTMLElement &&
-        (!useActiveDescendant || activeDescendantControlRef.current instanceof HTMLElement)
-      ) {
-        if (!disabled) {
-          const vanillaSettings: FocusZoneSettings = {
-            ...settings,
-            activeDescendantControl: activeDescendantControlRef.current ?? undefined
-          }
-          abortController.current = focusZone(containerRef.current, vanillaSettings)
-          return () => {
-            abortController.current?.abort()
-          }
-        } else {
-          abortController.current?.abort()
-        }
-      }
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [disabled, ...dependencies]
-  )
-
-  return {containerRef, activeDescendantControlRef}
-}

package/src/hooks/useOnEscapePress.ts

@@ -1,63 +0,0 @@
-import {useEffect, useCallback} from 'react'
-
-const handlers: ((e: KeyboardEvent) => void)[] = []
-
-/**
- * Calls all handlers in reverse order
- * @param event The KeyboardEvent generated by the Escape keydown.
- */
-function handleEscape(event: KeyboardEvent) {
-  if (event.key === 'Escape' && !event.defaultPrevented) {
-    for (let i = handlers.length - 1; i >= 0; --i) {
-      handlers[i](event)
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (event.defaultPrevented) {
-        break
-      }
-    }
-  }
-}
-
-/**
- * Sets up a `keydown` listener on `window.document`. If
- * 1) The pressed key is "Escape", and
- * 2) The event has not had `.preventDefault()` called
- * The given callback will be executed.
- *
- * Note: If multiple `useOnEscapePress` hooks are active simultaneously, the
- * callbacks will occur in reverse order. In other words, if a parent component
- * and a child component both call `useOnEscapePress`, when the user presses
- * Escape, the child component's callback will execute, followed by the parent's
- * callback. Each callback has the chance to call `.preventDefault()` on the
- * event to prevent further callbacks.
- *
- * @param callback {(e: KeyboardEvent) => void} The callback that gets executed
- * when the Escape key is pressed. The KeyboardEvent generated by the Escape
- * keypress is passed as the only argument.
- *
- * @param callbackDependencies {React.DependencyList} The dependencies of the given
- * `onEscape` callback for memoization. Omit this param if the callback is already
- * memoized. See `React.useCallback` for more info on memoization.
- */
-export const useOnEscapePress = (
-  onEscape: (e: KeyboardEvent) => void,
-  callbackDependencies: React.DependencyList = [onEscape]
-): void => {
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const escapeCallback = useCallback(onEscape, callbackDependencies)
-  useEffect(() => {
-    if (handlers.length === 0) {
-      document.addEventListener('keydown', handleEscape)
-    }
-    handlers.push(escapeCallback)
-    return () => {
-      handlers.splice(
-        handlers.findIndex(h => h === escapeCallback),
-        1
-      )
-      if (handlers.length === 0) {
-        document.removeEventListener('keydown', handleEscape)
-      }
-    }
-  }, [escapeCallback])
-}

package/src/hooks/useOnOutsideClick.tsx

@@ -1,82 +0,0 @@
-import React, {useEffect, useCallback, useMemo} from 'react'
-
-export type TouchOrMouseEvent = MouseEvent | TouchEvent
-type TouchOrMouseEventCallback = (event: TouchOrMouseEvent) => boolean | undefined
-
-export type UseOnOutsideClickSettings = {
-  containerRef: React.RefObject<HTMLDivElement>
-  ignoreClickRefs?: React.RefObject<HTMLElement>[]
-  onClickOutside: (e: TouchOrMouseEvent) => void
-}
-
-// Because events are handled at the document level, we provide a mechanism for early return.
-const stopPropagation = true
-
-/**
- * Calls all handlers in reverse order
- * @param event The MouseEvent generated by the click event.
- */
-function handleClick(event: MouseEvent) {
-  if (!event.defaultPrevented) {
-    for (const handler of Object.values(registry).reverse()) {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (handler(event) === stopPropagation || event.defaultPrevented) {
-        break
-      }
-    }
-  }
-}
-
-const registry: {[id: number]: TouchOrMouseEventCallback} = {}
-
-function register(id: number, handler: TouchOrMouseEventCallback): void {
-  registry[id] = handler
-}
-
-function deregister(id: number) {
-  delete registry[id]
-}
-
-// For auto-incrementing unique identifiers for registered handlers.
-let handlerId = 0
-
-export const useOnOutsideClick = ({containerRef, ignoreClickRefs, onClickOutside}: UseOnOutsideClickSettings) => {
-  const id = useMemo(() => handlerId++, [])
-
-  const handler = useCallback<TouchOrMouseEventCallback>(
-    event => {
-      // don't call click handler if the mouse event was triggered by an auxiliary button (right click/wheel button/etc)
-      if (event instanceof MouseEvent && event.button > 0) {
-        return stopPropagation
-      }
-
-      // don't call handler if the click happened inside of the container
-      if (containerRef.current?.contains(event.target as Node)) {
-        return stopPropagation
-      }
-
-      // don't call handler if click happened on an ignored ref
-      if (ignoreClickRefs && ignoreClickRefs.some(({current}) => current?.contains(event.target as Node))) {
-        return stopPropagation
-      }
-
-      onClickOutside(event)
-    },
-    [containerRef, ignoreClickRefs, onClickOutside]
-  )
-
-  useEffect(() => {
-    if (Object.keys(registry).length === 0) {
-      // use capture to ensure we get all events
-      document.addEventListener('mousedown', handleClick, {capture: true})
-    }
-    register(id, handler)
-
-    return () => {
-      deregister(id)
-      if (Object.keys(registry).length === 0) {
-        document.removeEventListener('mousedown', handleClick, {capture: true})
-      }
-    }
-  }, [id, handler])
-}

package/src/hooks/useOpenAndCloseFocus.ts

@@ -1,27 +0,0 @@
-import React, {useEffect} from 'react'
-import {iterateFocusableElements} from '../utils/iterateFocusableElements'
-
-export type UseOpenAndCloseFocusSettings = {
-  initialFocusRef?: React.RefObject<HTMLElement>
-  containerRef: React.RefObject<HTMLElement>
-  returnFocusRef: React.RefObject<HTMLElement>
-}
-
-export function useOpenAndCloseFocus({
-  initialFocusRef,
-  returnFocusRef,
-  containerRef
-}: UseOpenAndCloseFocusSettings): void {
-  useEffect(() => {
-    const returnRef = returnFocusRef.current
-    if (initialFocusRef && initialFocusRef.current) {
-      initialFocusRef.current.focus()
-    } else if (containerRef.current) {
-      const firstItem = iterateFocusableElements(containerRef.current).next().value
-      firstItem?.focus()
-    }
-    return function () {
-      returnRef?.focus()
-    }
-  }, [initialFocusRef, returnFocusRef, containerRef])
-}