@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/src/constants.ts

@@ -0,0 +1,62 @@
+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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,53 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,121 @@
+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

@@ -0,0 +1,80 @@
+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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1,82 @@
+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

@@ -0,0 +1,27 @@
+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])
+}