Update token components' APIs

.changeset/six-trains-guess.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Updates the API for token components to align with our size-naming ADR, avatar guidelines, and icon guidelines

docs/content/TextInputWithTokens.mdx

@@ -419,8 +419,8 @@ render(<WithIconAndLoadingIndicator />)
  />
  <PropsTableRow
  name="size"
- type="'small' | 'medium' | 'large' | 'extralarge'"
- defaultValue="extralarge"
+ type="'small' | 'medium' | 'large' | 'xlarge'"
+ defaultValue="xlarge"
  description="The size of the tokens and text input"
  />
  <PropsTableRow

docs/content/Token.mdx

@@ -55,7 +55,7 @@ All types of tokens may have the same interactive qualities as links or buttons.
  <Text fontSize={0} display="block" color="fg.subtle">
  With `leadingVisual` passed
  </Text>
- <Token text="Default Token" leadingVisual={() => <span>✨</span>} />
+ <Token text="Default Token" leadingVisual={GitBranchIcon} />
  </div>
 
  <div>
@@ -81,39 +81,37 @@ All types of tokens may have the same interactive qualities as links or buttons.
  gap: 2
  }}
  >
- <Token
- size="small"
- text="'small' Token"
- onRemove={() => {
- console.log('remove me')
- }}
- />
- <Token
- size="medium"
- text="'medium' Token"
- onRemove={() => {
- console.log('remove me')
- }}
- />
- <Token
- size="large"
- text="'large' Token (default)"
- onRemove={() => {
- console.log('remove me')
- }}
- />
- <Token
- size="extralarge"
- text="'extralarge' Token"
- onRemove={() => {
- console.log('remove me')
- }}
- />
+ <Token size="small" text="'small' Token" />
+ <Token size="medium" text="'medium' Token" />
+ <Token size="large" text="'large' Token (default)" />
+ <Token size="xlarge" text="'xlarge' Token" />
  </Box>
  </div>
 </Box>
 ```
 
+### With leadingVisual
+
+<Note variant="warning">
+ A <InlineCode>leadingVisual</InlineCode> should not be used with the <InlineCode>small</InlineCode> size option if
+ you're rendering an icon from Octicons
+</Note>
+
+```jsx live
+<Box
+ display="flex"
+ sx={{
+ alignItems: 'start',
+ flexDirection: 'column',
+ gap: 6
+ }}
+>
+ <Token size="medium" text="'medium' Token" leadingVisual={GitBranchIcon} />
+ <Token size="large" text="'large' Token (default)" leadingVisual={GitBranchIcon} />
+ <Token size="xlarge" text="'xlarge' Token" leadingVisual={GitBranchIcon} />
+</Box>
+```
+
 ### Interactive tokens
 
 If any token is interactive (it is a link or a button), it will become focusable, and react to being hovered or focused on.
@@ -267,8 +265,8 @@ Tokens that represent Issue labels should use the `IssueLabelToken` component.
  />
  <IssueLabelToken
  fillColor="#0366d6"
- size="extralarge"
- text="'extralarge' Token"
+ size="xlarge"
+ text="'xlarge' Token"
  onRemove={() => {
  console.log('remove me')
  }}
@@ -282,6 +280,11 @@ Tokens that represent Issue labels should use the `IssueLabelToken` component.
 
 Tokens that represent GitHub users should use the `AvatarToken` component.
 
+<Note variant="warning">
+ This component should not be used with the <InlineCode>small</InlineCode> or <InlineCode>medium</InlineCode> size
+ option
+</Note>
+
 ```jsx live
 <Box
  display="flex"
@@ -329,22 +332,6 @@ Tokens that represent GitHub users should use the `AvatarToken` component.
  gap: 2
  }}
  >
- <AvatarToken
- avatarSrc="https://avatars.githubusercontent.com/mperrotti"
- size="small"
- text="'small' Token"
- onRemove={() => {
- console.log('remove me')
- }}
- />
- <AvatarToken
- avatarSrc="https://avatars.githubusercontent.com/mperrotti"
- size="medium"
- text="'medium' Token"
- onRemove={() => {
- console.log('remove me')
- }}
- />
  <AvatarToken
  avatarSrc="https://avatars.githubusercontent.com/mperrotti"
  size="large"
@@ -355,8 +342,8 @@ Tokens that represent GitHub users should use the `AvatarToken` component.
  />
  <AvatarToken
  avatarSrc="https://avatars.githubusercontent.com/mperrotti"
- size="extralarge"
- text="'extralarge' Token"
+ size="xlarge"
+ text="'xlarge' Token"
  onRemove={() => {
  console.log('remove me')
  }}

src/TextInputWithTokens.tsx

@@ -59,7 +59,8 @@ const overflowCountFontSizeMap: Record<TokenSizeKeys, number> = {
  small: 0,
  medium: 1,
  large: 1,
- extralarge: 2
+ extralarge: 2,
+ xlarge: 2 // will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
 }
 
 // using forwardRef is important so that other components (ex. Autocomplete) can use the ref
@@ -239,7 +240,8 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
  small: 'small',
  medium: 'small',
  large: 'medium',
- extralarge: 'medium'
+ extralarge: 'medium',
+ xlarge: 'medium' // will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
  }
  const showLeadingLoadingIndicator =
  loading && (loaderPosition === 'leading' || Boolean(LeadingVisual && loaderPosition !== 'trailing'))
@@ -370,7 +372,7 @@ const TextInputWithTokens = React.forwardRef(TextInputWithTokensInnerComponent)
 
 TextInputWithTokens.defaultProps = {
  tokenComponent: Token,
- size: 'extralarge',
+ size: 'xlarge',
  hideTokenRemoveButtons: false,
  preventTokenWrapping: false,
  loaderPosition: 'auto'

src/Token/AvatarToken.tsx

@@ -5,6 +5,7 @@ import {TokenBaseProps, defaultTokenSize, tokenSizes, TokenSizeKeys} from './Tok
 import Token from './Token'
 import {Avatar} from '..'
 
+// TODO: update props to only accept 'large' and 'xlarge' on the next breaking change
 export interface AvatarTokenProps extends TokenBaseProps {
  avatarSrc: string
 }

src/Token/IssueLabelToken.tsx

@@ -11,10 +11,6 @@ export interface IssueLabelTokenProps extends TokenBaseProps {
  * The color that corresponds to the label
  */
  fillColor?: string
- /**
- * Whether the remove button should be rendered in the token
- */
- hideRemoveButton?: boolean
 }
 
 const tokenBorderWidthPx = 1

src/Token/Token.tsx

@@ -12,10 +12,6 @@ export interface TokenProps extends TokenBaseProps {
  */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  leadingVisual?: React.ComponentType<any>
- /**
- * Whether the remove button should be rendered in the token
- */
- hideRemoveButton?: boolean
 }
 
 const tokenBorderWidthPx = 1
@@ -52,6 +48,7 @@ const LeadingVisualContainer = styled('span')<Pick<TokenBaseProps, 'size'>>`
  switch (props.size) {
  case 'large':
  case 'extralarge':
+ case 'xlarge':
  return css`
  margin-right: ${get('space.2')};
  `

src/Token/TokenBase.tsx

@@ -4,13 +4,19 @@ import {variant} from 'styled-system'
 import {get} from '../constants'
 import sx, {SxProp} from '../sx'
 
-export type TokenSizeKeys = 'small' | 'medium' | 'large' | 'extralarge'
+// TODO: remove invalid "extralarge" size name in next breaking change
+/** @deprecated 'extralarge' to be removed to align with size naming ADR https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md **/
+type ExtraLarge = 'extralarge'
+export type TokenSizeKeys = 'small' | 'medium' | 'large' | 'xlarge' | ExtraLarge
+
+const xlargeSize = '32px'
 
 export const tokenSizes: Record<TokenSizeKeys, string> = {
  small: '16px',
  medium: '20px',
  large: '24px',
- extralarge: '32px'
+ extralarge: xlargeSize,
+ xlarge: xlargeSize
 }
 
 export const defaultTokenSize: TokenSizeKeys = 'medium'
@@ -22,6 +28,10 @@ export interface TokenBaseProps
  * The function that gets called when a user clicks the remove button, or keys "Backspace" or "Delete" when focused on the token
  */
  onRemove?: () => void
+ /**
+ * Whether the remove button should be rendered in the token
+ */
+ hideRemoveButton?: boolean
  /**
  * Whether the token is selected
  */
@@ -43,6 +53,16 @@ export interface TokenBaseProps
 export const isTokenInteractive = ({as = 'span', onClick, onFocus, tabIndex = -1}: TokenBaseProps) =>
  Boolean(onFocus || onClick || tabIndex > -1 || ['a', 'button'].includes(as))
 
+const xlargeVariantStyles = {
+ fontSize: 1,
+ height: tokenSizes.xlarge,
+ lineHeight: tokenSizes.xlarge,
+ paddingLeft: 3,
+ paddingRight: 3,
+ paddingTop: 0,
+ paddingBottom: 0
+}
+
 const variants = variant<
  {
  fontSize: number
@@ -87,15 +107,8 @@ const variants = variant<
  paddingTop: 0,
  paddingBottom: 0
  },
- extralarge: {
- fontSize: 1,
- height: tokenSizes.extralarge,
- lineHeight: tokenSizes.extralarge,
- paddingLeft: 3,
- paddingRight: 3,
- paddingTop: 0,
- paddingBottom: 0
- }
+ extralarge: xlargeVariantStyles,
+ xlarge: xlargeVariantStyles
  }
 })
 

src/Token/_RemoveTokenButton.tsx

@@ -31,6 +31,11 @@ const variants = variant<{height: string; width: string}, TokenSizeKeys>({
  extralarge: {
  height: tokenSizes.extralarge,
  width: tokenSizes.extralarge
+ },
+ // xlarge will eventually replace "extralarge" per this ADR: https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md
+ xlarge: {
+ height: tokenSizes.xlarge,
+ width: tokenSizes.xlarge
  }
  }
 })
@@ -58,6 +63,7 @@ const StyledTokenButton = styled.span<TokenButtonProps & SxProp>`
  switch (props.size) {
  case 'large':
  case 'extralarge':
+ case 'xlarge':
  return css`
  margin-left: ${get('space.2')};
  `