@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/src/hooks/useOverlay.tsx

@@ -0,0 +1,32 @@
+import {useOnOutsideClick, TouchOrMouseEvent} from './useOnOutsideClick'
+import {useOpenAndCloseFocus} from './useOpenAndCloseFocus'
+import {useOnEscapePress} from './useOnEscapePress'
+import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
+
+export type UseOverlaySettings = {
+  ignoreClickRefs?: React.RefObject<HTMLElement>[]
+  initialFocusRef?: React.RefObject<HTMLElement>
+  returnFocusRef: React.RefObject<HTMLElement>
+  onEscape: (e: KeyboardEvent) => void
+  onClickOutside: (e: TouchOrMouseEvent) => void
+  overlayRef?: React.RefObject<HTMLDivElement>
+}
+
+export type OverlayReturnProps = {
+  ref: React.RefObject<HTMLDivElement>
+}
+
+export const useOverlay = ({
+  overlayRef: _overlayRef,
+  returnFocusRef,
+  initialFocusRef,
+  onEscape,
+  ignoreClickRefs,
+  onClickOutside
+}: UseOverlaySettings): OverlayReturnProps => {
+  const overlayRef = useProvidedRefOrCreate<HTMLDivElement>(_overlayRef)
+  useOpenAndCloseFocus({containerRef: overlayRef, returnFocusRef, initialFocusRef})
+  useOnOutsideClick({containerRef: overlayRef, ignoreClickRefs, onClickOutside})
+  useOnEscapePress(onEscape)
+  return {ref: overlayRef}
+}

package/src/hooks/useProvidedRefOrCreate.ts

@@ -0,0 +1,14 @@
+import React from 'react'
+
+/**
+ * There are some situations where we only want to create a new ref if one is not provided to a component
+ * or hook as a prop. However, due to the `rules-of-hooks`, we cannot conditionally make a call to `React.useRef`
+ * only in the situations where the ref is not provided as a prop.
+ * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
+ * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
+ * @type TRef The type of the RefObject which should be created.
+ */
+export function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef>): React.RefObject<TRef> {
+  const createdRef = React.useRef<TRef>(null)
+  return providedRef ?? createdRef
+}

package/src/hooks/useProvidedStateOrCreate.ts

@@ -0,0 +1,27 @@
+import {useCallback, useState} from 'react'
+
+/**
+ * There are some situations where we want to give users the option to control state externally with their own state handlers
+ * or default to using internal state handlers. Because of the 'rules-of-hooks', we cannot conditionally make a call to `React.useState`
+ * only in the situations where the state is not provided as a prop.
+ * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
+ * @param externalState The state to use - if undefined, will use the state from a call to React.useState
+ * @param setExternalState The setState to use - if undefined, will use the setState from a call to React.useState
+ * @param defaultState The defaultState to use, if using internal state.
+ */
+export function useProvidedStateOrCreate<T>(
+  externalState: T | undefined,
+  setExternalState: ((s: T) => void) | undefined,
+  defaultState: T
+) {
+  const [internalState, setInternalState] = useState<T>(defaultState)
+  const state = externalState ?? internalState
+  const setState = useCallback(
+    (s: T) => {
+      setInternalState(s)
+      if (setExternalState) setExternalState(s)
+    },
+    [setExternalState]
+  )
+  return [state, setState] as const
+}

package/src/hooks/useRenderForcingRef.ts

@@ -0,0 +1,22 @@
+import {MutableRefObject, RefObject, useCallback, useRef, useState} from 'react'
+
+/**
+ * There are certain situations where a ref might be set after the current render cycle for a
+ * component has finished.  e.g. a forward ref from a conditionally rendered child component.
+ * In these situations, we need to force a re-render, which is done here by the useState hook.
+ * @type TRef The type of the RefObject which should be created.
+ */
+export function useRenderForcingRef<TRef>() {
+  const [refCurrent, setRefCurrent] = useState<TRef | null>(null)
+  const ref = useRef<TRef>(null) as MutableRefObject<TRef | null>
+  ref.current = refCurrent
+
+  const setRef = useCallback(
+    (newRef: TRef | null) => {
+      ref.current = newRef
+      setRefCurrent(newRef)
+    },
+    [ref]
+  )
+  return [ref as RefObject<TRef>, setRef] as const
+}

package/src/hooks/useResizeObserver.ts

@@ -0,0 +1,11 @@
+import React from 'react'
+
+export function useResizeObserver(callback: () => void) {
+  React.useLayoutEffect(() => {
+    const observer = new window.ResizeObserver(() => callback())
+    observer.observe(document.documentElement)
+    return () => {
+      observer.disconnect()
+    }
+  }, [callback])
+}

package/src/hooks/useSafeTimeout.ts

@@ -0,0 +1,38 @@
+import {useCallback, useEffect, useRef} from 'react'
+
+type SetTimeout = (handler: TimerHandler, timeout?: number, ...args: unknown[]) => number
+type ClearTimeout = (id: number) => void
+
+/**
+ * Safely call `setTimeout` and `clearTimeout` within a component.
+ *
+ * This hook ensures that all timeouts are cleared when the component unmounts.
+ */
+export default function useSafeTimeout(): {safeSetTimeout: SetTimeout; safeClearTimeout: ClearTimeout} {
+  const timers = useRef<Set<number>>(new Set<number>())
+
+  const safeSetTimeout = useCallback(
+    (handler: TimerHandler, timeout?: number | undefined, ...args: unknown[]): number => {
+      const id = window.setTimeout(handler, timeout, ...args)
+      timers.current.add(id)
+      return id
+    },
+    []
+  )
+
+  const safeClearTimeout = useCallback((id: number) => {
+    clearTimeout(id)
+    timers.current.delete(id)
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      for (const id of timers.current) {
+        clearTimeout(id)
+      }
+    }
+  }, [])
+
+  return {safeSetTimeout, safeClearTimeout}
+}

package/src/hooks/useScrollFlash.ts

@@ -0,0 +1,21 @@
+import React, {useEffect} from 'react'
+/**
+ * This hook will flash the scrollbars for a ref of a container that has scrollable overflow
+ * @param scrollContainerRef The ref of the scrollable content
+ */
+export default function useScrollFlash(scrollContainerRef: React.RefObject<HTMLElement>) {
+  // https://adxlv.computer/projects/flash-scrollers/
+  useEffect(() => {
+    const scrollContainer = scrollContainerRef.current
+    if (!scrollContainer) {
+      return
+    }
+    const currentScroll = scrollContainer.scrollTop
+    const maxScroll = scrollContainer.scrollHeight
+
+    const altScroll = currentScroll < Math.min(1, maxScroll) ? currentScroll + 1 : currentScroll - 1
+
+    scrollContainer.scrollTop = altScroll
+    scrollContainer.scrollTop = currentScroll
+  }, [scrollContainerRef])
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+export {default as theme} from './theme'
+export {get as themeGet} from './constants'
+export {default as BaseStyles} from './BaseStyles'
+export type {BaseStylesProps} from './BaseStyles'
+export {default as ThemeProvider, useTheme, useColorSchemeVar} from './ThemeProvider'
+export type {ThemeProviderProps} from './ThemeProvider'
+
+// Layout
+export {default as BorderBox} from './BorderBox'
+export type {BorderBoxProps} from './BorderBox'
+export {default as Box} from './Box'
+export type {BoxProps} from './Box'
+export {default as Flex} from './Flex'
+export type {FlexProps} from './Flex'
+export {default as Grid} from './Grid'
+export type {GridProps} from './Grid'
+export {default as Position, Absolute, Fixed, Relative, Sticky} from './Position'
+export type {PositionProps, AbsoluteProps, FixedProps, RelativeProps, StickyProps} from './Position'
+
+// Hooks
+export {default as useDetails} from './hooks/useDetails'
+export {default as useSafeTimeout} from './hooks/useSafeTimeout'
+export {useOnOutsideClick} from './hooks/useOnOutsideClick'
+export {useOpenAndCloseFocus} from './hooks/useOpenAndCloseFocus'
+export {useOnEscapePress} from './hooks/useOnEscapePress'
+export {useOverlay} from './hooks/useOverlay'
+export {useConfirm} from './Dialog/ConfirmationDialog'
+
+// Components
+export {ActionList} from './ActionList'
+export {ActionMenu} from './ActionMenu'
+export type {ActionMenuProps} from './ActionMenu'
+export {default as Avatar} from './Avatar'
+export type {AvatarProps} from './Avatar'
+export {default as AvatarPair} from './AvatarPair'
+export type {AvatarPairProps} from './AvatarPair'
+export {default as AvatarStack} from './AvatarStack'
+export type {AvatarStackProps} from './AvatarStack'
+export {default as BranchName} from './BranchName'
+export type {BranchNameProps} from './BranchName'
+export {default as Breadcrumb} from './Breadcrumb'
+export type {BreadcrumbProps, BreadcrumbItemProps} from './Breadcrumb'
+export {
+  default as Button,
+  ButtonDanger,
+  ButtonOutline,
+  ButtonPrimary,
+  ButtonInvisible,
+  ButtonTableList,
+  ButtonClose,
+  ButtonGroup
+} from './Button'
+export type {
+  ButtonProps,
+  ButtonDangerProps,
+  ButtonOutlineProps,
+  ButtonPrimaryProps,
+  ButtonInvisibleProps,
+  ButtonTableListProps,
+  ButtonCloseProps,
+  ButtonGroupProps
+} from './Button'
+export {default as Caret} from './Caret'
+export type {CaretProps} from './Caret'
+export {default as CircleBadge} from './CircleBadge'
+export type {CircleBadgeProps, CircleBadgeIconProps} from './CircleBadge'
+export {default as CircleOcticon} from './CircleOcticon'
+export type {CircleOcticonProps} from './CircleOcticon'
+export {default as CounterLabel} from './CounterLabel'
+export type {CounterLabelProps} from './CounterLabel'
+export {default as Details} from './Details'
+export type {DetailsProps} from './Details'
+export {default as Dialog} from './Dialog'
+export type {DialogProps, DialogHeaderProps} from './Dialog'
+export {ConfirmationDialog} from './Dialog/ConfirmationDialog'
+export {default as Dropdown} from './Dropdown'
+export type {
+  DropdownProps,
+  DropdownCaretProps,
+  DropdownButtonProps,
+  DropdownItemProps,
+  DropdownMenuProps
+} from './Dropdown'
+export {DropdownButton, DropdownMenu} from './DropdownMenu'
+// not exporting new DropdownMenu types yet due to conflict with Dropdown types above
+// export type {DropdownButtonProps, DropdownMenuProps} from './DropdownMenu'
+export {default as FilteredSearch} from './FilteredSearch'
+export type {FilteredSearchProps} from './FilteredSearch'
+export {default as FilterList} from './FilterList'
+export type {FilterListProps, FilterListItemProps} from './FilterList'
+export {default as Flash} from './Flash'
+export type {FlashProps} from './Flash'
+export {default as FormGroup} from './FormGroup'
+export type {FormGroupProps, FormGroupLabelProps} from './FormGroup'
+export {default as Header} from './Header'
+export type {HeaderProps, HeaderItemProps, HeaderLinkProps} from './Header'
+export {default as Heading} from './Heading'
+export type {HeadingProps} from './Heading'
+export {default as LabelGroup} from './LabelGroup'
+export type {LabelGroupProps} from './LabelGroup'
+export {default as Label} from './Label'
+export type {LabelProps} from './Label'
+export {default as Link} from './Link'
+export type {LinkProps} from './Link'
+export {default as Overlay} from './Overlay'
+export type {OverlayProps} from './Overlay'
+export {default as Pagehead} from './Pagehead'
+export type {PageheadProps} from './Pagehead'
+export {default as Pagination} from './Pagination'
+export type {PaginationProps} from './Pagination'
+export {default as PointerBox} from './PointerBox'
+export type {PointerBoxProps} from './PointerBox'
+export {default as Popover} from './Popover'
+export type {PopoverProps, PopoverContentProps} from './Popover'
+// export {default as Portal, registerPortalRoot} from './Portal'
+// export type {PortalProps} from './Portal'
+export {default as ProgressBar} from './ProgressBar'
+export type {ProgressBarProps} from './ProgressBar'
+export {default as SelectMenu} from './SelectMenu'
+export type {
+  SelectMenuProps,
+  SelectMenuDividerProps,
+  SelectMenuFilterProps,
+  SelectMenuFooterProps,
+  SelectMenuItemProps,
+  SelectMenuListProps,
+  SelectMenuModalProps,
+  SelectMenuTabsProps,
+  SelectMenuHeaderProps,
+  SelectMenuTabProps,
+  SelectMenuTabPanelProps,
+  SelectMenuLoadingAnimationProps
+} from './SelectMenu'
+export {default as SideNav} from './SideNav'
+export type {SideNavProps, SideNavLinkProps} from './SideNav'
+export {default as Spinner} from './Spinner'
+export type {SpinnerProps} from './Spinner'
+export {default as StateLabel} from './StateLabel'
+export type {StateLabelProps} from './StateLabel'
+export {default as StyledOcticon} from './StyledOcticon'
+export type {StyledOcticonProps} from './StyledOcticon'
+export {default as SubNav} from './SubNav'
+export type {SubNavProps, SubNavLinkProps, SubNavLinksProps} from './SubNav'
+export {default as TabNav} from './TabNav'
+export type {TabNavProps, TabNavLinkProps} from './TabNav'
+export {default as TextInput} from './TextInput'
+export type {TextInputProps} from './TextInput'
+export {default as Text} from './Text'
+export type {TextProps} from './Text'
+export {default as Timeline} from './Timeline'
+export type {
+  TimelineProps,
+  TimelineBadgeProps,
+  TimelineBodyProps,
+  TimelineBreakProps,
+  TimelineItemsProps
+} from './Timeline'
+export {default as Tooltip} from './Tooltip'
+export type {TooltipProps} from './Tooltip'
+export {default as Truncate} from './Truncate'
+export type {TruncateProps} from './Truncate'
+export {default as UnderlineNav} from './UnderlineNav'
+export type {UnderlineNavProps, UnderlineNavLinkProps} from './UnderlineNav'
+
+export {SSRProvider, useSSRSafeId} from './utils/ssr'

package/src/polyfills/eventListenerSignal.ts

@@ -0,0 +1,66 @@
+/*
+
+This file polyfills the following: https://github.com/whatwg/dom/issues/911
+Once all targeted browsers support this DOM feature, this polyfill can be deleted.
+
+This allows users to pass an AbortSignal to a call to addEventListener as part of the
+AddEventListenerOptions object. When the signal is aborted, the event listener is
+removed.
+
+*/
+
+let signalSupported = false
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+function noop() {}
+try {
+  const options = Object.create(
+    {},
+    {
+      signal: {
+        get() {
+          signalSupported = true
+        }
+      }
+    }
+  )
+  window.addEventListener('test', noop, options)
+  window.removeEventListener('test', noop, options)
+} catch (e) {
+  /* */
+}
+function featureSupported(): boolean {
+  return signalSupported
+}
+
+function monkeyPatch() {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  const originalAddEventListener = EventTarget.prototype.addEventListener
+  EventTarget.prototype.addEventListener = function (name, originalCallback, optionsOrCapture) {
+    if (
+      typeof optionsOrCapture === 'object' &&
+      'signal' in optionsOrCapture &&
+      optionsOrCapture.signal instanceof AbortSignal
+    ) {
+      originalAddEventListener.call(optionsOrCapture.signal, 'abort', () => {
+        this.removeEventListener(name, originalCallback, optionsOrCapture)
+      })
+    }
+    return originalAddEventListener.call(this, name, originalCallback, optionsOrCapture)
+  }
+}
+
+export function polyfill(): void {
+  if (!featureSupported()) {
+    monkeyPatch()
+    signalSupported = true
+  }
+}
+
+declare global {
+  interface AddEventListenerOptions {
+    signal?: AbortSignal
+  }
+}