@primer/components 29.1.1 → 30.0.0-rc.48fd5c94

package/src/ActionList/index.ts

@@ -0,0 +1,21 @@
+import {List} from './List'
+import {Group} from './Group'
+import {Item} from './Item'
+import {Divider} from './Divider'
+export type {ListProps as ActionListProps} from './List'
+export type {GroupProps} from './Group'
+export type {ItemProps} from './Item'
+
+/**
+ * Collection of list-related components.
+ */
+export const ActionList = Object.assign(List, {
+  /** Collects related `Items` in an `ActionList`. */
+  Group,
+
+  /** An actionable or selectable `Item` with an optional icon and description. */
+  Item,
+
+  /** Visually separates `Item`s or `Group`s in an `ActionList`. */
+  Divider
+})

package/src/ActionMenu.tsx

@@ -0,0 +1,106 @@
+import {GroupedListProps, List, ListPropsBase} from './ActionList/List'
+import {Item, ItemProps} from './ActionList/Item'
+import {Divider} from './ActionList/Divider'
+import Button, {ButtonProps} from './Button'
+import React, {useCallback, useMemo} from 'react'
+import {AnchoredOverlay} from './AnchoredOverlay'
+import {useProvidedStateOrCreate} from './hooks/useProvidedStateOrCreate'
+import {OverlayProps} from './Overlay'
+import {useProvidedRefOrCreate} from './hooks'
+import {AnchoredOverlayWrapperAnchorProps} from './AnchoredOverlay/AnchoredOverlay'
+
+interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
+  /**
+   * Content that is passed into the renderAnchor component, which is a button by default.
+   */
+  anchorContent?: React.ReactNode
+
+  /**
+   * A callback that triggers both on clicks and keyboard events. This callback will be overridden by item level `onAction` callbacks.
+   */
+  onAction?: (props: ItemProps, event?: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => void
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `setOpen`.
+   */
+  open?: boolean
+
+  /**
+   * If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.
+   */
+  setOpen?: (s: boolean) => void
+
+  /**
+   * Props to be spread on the internal `Overlay` component.
+   */
+  overlayProps?: Partial<OverlayProps>
+}
+
+export type ActionMenuProps = ActionMenuBaseProps & AnchoredOverlayWrapperAnchorProps
+
+const ActionMenuItem = (props: ItemProps) => <Item role="menuitem" {...props} />
+
+ActionMenuItem.displayName = 'ActionMenu.Item'
+
+const ActionMenuBase = ({
+  anchorContent,
+  renderAnchor = <T extends ButtonProps>(props: T) => <Button {...props} />,
+  anchorRef: externalAnchorRef,
+  onAction,
+  open,
+  setOpen,
+  overlayProps,
+  items,
+  ...listProps
+}: ActionMenuProps): JSX.Element => {
+  const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, setOpen, false)
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const onOpen = useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
+  const onClose = useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
+
+  const renderMenuAnchor = useMemo(() => {
+    if (renderAnchor === null) {
+      return null
+    }
+    return <T extends React.HTMLAttributes<HTMLElement>>(props: T) => {
+      return renderAnchor({
+        'aria-label': 'menu',
+        children: anchorContent,
+        ...props
+      })
+    }
+  }, [anchorContent, renderAnchor])
+
+  const itemsToRender = useMemo(() => {
+    return items.map(item => {
+      return {
+        ...item,
+        role: 'menuitem',
+        onAction: (props, event) => {
+          const actionCallback = item.onAction ?? onAction
+          actionCallback?.(props as ItemProps, event)
+          if (!event.defaultPrevented) {
+            onClose()
+          }
+        }
+      } as ItemProps
+    })
+  }, [items, onAction, onClose])
+
+  return (
+    <AnchoredOverlay
+      renderAnchor={renderMenuAnchor}
+      anchorRef={anchorRef}
+      open={combinedOpenState}
+      onOpen={onOpen}
+      onClose={onClose}
+      overlayProps={overlayProps}
+    >
+      <List {...listProps} role="menu" items={itemsToRender} />
+    </AnchoredOverlay>
+  )
+}
+
+ActionMenuBase.displayName = 'ActionMenu'
+
+export const ActionMenu = Object.assign(ActionMenuBase, {Divider, Item: ActionMenuItem})

package/src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -0,0 +1,180 @@
+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'
+
+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)
+
+/**
+ * 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
+}) => {
+  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
+    },
+    [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'

package/src/AnchoredOverlay/index.ts

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

package/src/Avatar.tsx

@@ -0,0 +1,46 @@
+import styled from 'styled-components'
+import {COMMON, get, SystemCommonProps} 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
+} & SystemCommonProps &
+  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)};
+  ${COMMON};
+  ${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,161 @@
+import classnames from 'classnames'
+import React from 'react'
+import styled from 'styled-components'
+import {COMMON, get, SystemCommonProps} from './constants'
+import {Box} from '.'
+import sx, {SxProp} from './sx'
+import {ComponentProps} from './utils/types'
+
+type StyledAvatarStackWrapperProps = {
+  count?: number
+} & SystemCommonProps &
+  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;
+      }
+    }
+  }
+
+  ${COMMON}
+  ${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
+} & ComponentProps<typeof AvatarStackWrapper>
+
+const AvatarStack = ({children, alignRight, ...rest}: 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} {...rest}>
+      <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: 'text.primary',
+  fontFamily: 'normal',
+  lineHeight: 'default'
+}
+
+export default BaseStyles

package/src/BorderBox.tsx

@@ -0,0 +1,18 @@
+import styled from 'styled-components'
+import Box, {BoxProps} from './Box'
+
+export type BorderBoxProps = BoxProps
+
+/**
+ * @deprecated Use the Box component instead (i.e. <BorderBox> → <Box borderWidth='1px' borderStyle='solid' borderColor='border.primary' borderRadius={2}>)
+ */
+const BorderBox = styled(Box)``
+
+BorderBox.defaultProps = {
+  borderWidth: '1px',
+  borderStyle: 'solid',
+  borderColor: 'border.primary',
+  borderRadius: 2
+}
+
+export default BorderBox

package/src/Box.tsx

@@ -0,0 +1,54 @@
+import styled from 'styled-components'
+import {
+  background,
+  BackgroundProps,
+  border,
+  BorderProps,
+  color,
+  ColorProps,
+  flexbox,
+  FlexboxProps,
+  grid,
+  GridProps,
+  layout,
+  LayoutProps,
+  position,
+  PositionProps,
+  shadow,
+  ShadowProps,
+  space,
+  SpaceProps,
+  typography,
+  TypographyProps
+} from 'styled-system'
+import sx, {SxProp} from './sx'
+import {ComponentProps} from './utils/types'
+
+type StyledBoxProps = SpaceProps &
+  ColorProps &
+  TypographyProps &
+  LayoutProps &
+  FlexboxProps &
+  GridProps &
+  BackgroundProps &
+  BorderProps &
+  PositionProps &
+  ShadowProps &
+  SxProp
+
+const Box = styled.div<StyledBoxProps>(
+  space,
+  color,
+  typography,
+  layout,
+  flexbox,
+  grid,
+  background,
+  border,
+  position,
+  shadow,
+  sx
+)
+
+export type BoxProps = ComponentProps<typeof Box>
+export default Box

package/src/BranchName.tsx

@@ -0,0 +1,19 @@
+import styled from 'styled-components'
+import {COMMON, get, SystemCommonProps} from './constants'
+import sx, {SxProp} from './sx'
+import {ComponentProps} from './utils/types'
+
+const BranchName = styled.a<SystemCommonProps & SxProp>`
+  display: inline-block;
+  padding: 2px 6px;
+  font-size: ${get('fontSizes.0')};
+  font-family: ${get('fonts.mono')};
+  color: ${get('colors.fg.muted')};
+  background-color: ${get('colors.accent.subtle')};
+  border-radius: ${get('radii.2')};
+  ${COMMON};
+  ${sx};
+`
+
+export type BranchNameProps = ComponentProps<typeof BranchName>
+export default BranchName