BranchName: Add leadingVisual, trailingAction and description

.changeset/whole-rings-glow.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+BranchName: Add `LeadingVisual` and `TrailingAction` subcomponents and a `description` prop

e2e/components/BranchName.test.ts

@@ -14,10 +14,27 @@ const stories = [
     focus: false,
   },
   {
+    // Note: the story was renamed to "With Leading Visual" but we keep the
+    // snapshot title as "With A Branch Icon" so the VRT diff stays usable.
     title: 'With A Branch Icon',
-    id: 'components-branchname-features--with-branch-icon',
+    id: 'components-branchname-features--with-leading-visual',
     focus: false,
   },
+  {
+    title: 'Link Without Href',
+    id: 'components-branchname-features--link-without-href',
+    focus: true,
+  },
+  {
+    title: 'No Props',
+    id: 'components-branchname-features--no-props',
+    focus: false,
+  },
+  {
+    title: 'With Description',
+    id: 'components-branchname-features--with-description',
+    focus: true,
+  },
   {
     title: 'With Trailing Action',
     id: 'components-branchname-features--with-trailing-action',
@@ -28,6 +45,11 @@ const stories = [
     id: 'components-branchname-features--with-trailing-action-menu',
     focus: false,
   },
+  {
+    title: 'Kitchen Sink',
+    id: 'components-branchname-features--kitchen-sink',
+    focus: false,
+  },
 ] as const
 
 test.describe('BranchName', () => {

packages/react/src/BranchName/BranchName.docs.json

@@ -8,7 +8,16 @@
       "id": "components-branchname--default"
     },
     {
-      "id": "components-branchname-features--with-branch-icon"
+      "id": "components-branchname-features--with-leading-visual"
+    },
+    {
+      "id": "components-branchname-features--with-description"
+    },
+    {
+      "id": "components-branchname-features--with-trailing-action"
+    },
+    {
+      "id": "components-branchname-features--with-trailing-action-menu"
     },
     {
       "id": "components-branchname-features--not-a-link"
@@ -24,7 +33,88 @@
       "name": "as",
       "type": "React.ElementType",
       "defaultValue": "\"a\""
+    },
+    {
+      "name": "children",
+      "type": "React.ReactNode",
+      "required": false,
+      "description": "The branch name, optionally including BranchName.LeadingVisual and BranchName.TrailingAction subcomponents.",
+      "defaultValue": ""
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "required": false,
+      "description": "Description tooltip text. Provides additional context for the branch name and is exposed to assistive technology via `aria-describedby`.",
+      "defaultValue": ""
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "description": "Custom className",
+      "defaultValue": ""
     }
   ],
-  "subcomponents": []
+  "subcomponents": [
+    {
+      "name": "BranchName.LeadingVisual",
+      "props": [
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "required": false,
+          "description": "The leading visual content, typically an octicon. We recommend using `GitBranchIcon` to represent a branch.",
+          "defaultValue": ""
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "A custom class name that is merged with the leading visual's class. Additional `span` props are forwarded to the underlying element.",
+          "defaultValue": ""
+        }
+      ]
+    },
+    {
+      "name": "BranchName.TrailingAction",
+      "props": [
+        {
+          "name": "icon",
+          "type": "React.ComponentType",
+          "required": true,
+          "description": "Provide an octicon. It will be placed in the center of the action button.",
+          "defaultValue": ""
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": true,
+          "description": "Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text.",
+          "defaultValue": ""
+        },
+        {
+          "name": "onClick",
+          "type": "React.MouseEventHandler<HTMLButtonElement>",
+          "required": false,
+          "description": "Handler called when the trailing action button is clicked.",
+          "defaultValue": ""
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "A custom class name that is merged with the action button's class. Additional `button` props are forwarded to the underlying button.",
+          "defaultValue": ""
+        },
+        {
+          "name": "ref",
+          "type": "React.RefObject<HTMLButtonElement>",
+          "required": false,
+          "description": "A ref forwarded to the underlying action button.",
+          "defaultValue": ""
+        }
+      ]
+    }
+  ]
 }

packages/react/src/BranchName/BranchName.features.stories.tsx

@@ -1,29 +1,22 @@
 import type {Meta} from '@storybook/react-vite'
-import React, {useState} from 'react'
+import React, {useState, useRef} from 'react'
 import BranchName from './BranchName'
-import {Stack} from '../Stack'
-import Octicon from '../Octicon'
 import {GitBranchIcon, CopyIcon, CheckIcon, TriangleDownIcon} from '@primer/octicons-react'
-import {IconButton} from '../Button'
-import {Tooltip} from '../TooltipV2'
 import {SelectPanel} from '../SelectPanel'
 import type {ItemInput} from '../FilteredActionList'
-import {clsx} from 'clsx'
 import {announce} from '@primer/live-region-element'
 
-import styles from './BranchName.stories.module.css'
-
 export default {
   title: 'Components/BranchName/Features',
   component: BranchName,
 } as Meta<typeof BranchName>
 
-export const WithBranchIcon = () => (
+export const WithLeadingVisual = () => (
   <BranchName href="#">
-    <Stack direction="horizontal" gap="condensed" align="center">
-      <Octicon icon={GitBranchIcon} />
-      branch_name
-    </Stack>
+    <BranchName.LeadingVisual>
+      <GitBranchIcon />
+    </BranchName.LeadingVisual>
+    branch_name
   </BranchName>
 )
 
@@ -38,6 +31,18 @@ export const LinkWithoutHref = () => (
 
 export const NoProps = () => <BranchName>branch_name_no_props</BranchName>
 
+export const WithDescription = ({
+  branchName = 'fix/anchored-overlay-outside-top-autogrow',
+  repo = 'primer/react',
+}: {
+  branchName: string
+  repo: string
+}) => (
+  <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+    {branchName}
+  </BranchName>
+)
+
 export const WithTrailingAction = ({
   branchName = 'fix/anchored-overlay-outside-top-autogrow',
   repo = 'primer/react',
@@ -54,26 +59,15 @@ export const WithTrailingAction = ({
     setTimeout(() => setCopied(false), 2000)
   }
 
-  const tooltipText = copied ? 'Copied!' : 'Copy branch name to clipboard'
-
   return (
-    <span className={styles.BranchNameWithTrailingAction}>
-      <Tooltip text={`${repo}:${branchName}`}>
-        <BranchName href={`https://github.com/${repo}/tree/${branchName}`} className={styles.BranchNameTransparent}>
-          {branchName}
-        </BranchName>
-      </Tooltip>
-      <Tooltip text={tooltipText} aria-hidden>
-        <IconButton
-          icon={copied ? CheckIcon : CopyIcon}
-          aria-label="Copy branch name to clipboard"
-          variant="invisible"
-          size="small"
-          onClick={handleCopy}
-          className={clsx(styles.TrailingActionButton, copied && styles.TrailingActionButtonCopied)}
-        />
-      </Tooltip>
-    </span>
+    <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+      {branchName}
+      <BranchName.TrailingAction
+        icon={copied ? CheckIcon : CopyIcon}
+        aria-label="Copy branch name to clipboard"
+        onClick={handleCopy}
+      />
+    </BranchName>
   )
 }
 
@@ -94,6 +88,7 @@ export const WithTrailingActionMenu = ({repo = 'primer/react'}: {repo: string})
   const [selected, setSelected] = useState<ItemInput>(branches[0])
   const [filter, setFilter] = useState('')
   const [open, setOpen] = useState(false)
+  const anchorRef = useRef<HTMLButtonElement>(null)
 
   const filteredBranches = branches.filter(branch => branch.text?.toLowerCase().includes(filter.toLowerCase()))
 
@@ -104,21 +99,19 @@ export const WithTrailingActionMenu = ({repo = 'primer/react'}: {repo: string})
   }
 
   return (
-    <span className={styles.BranchNameWithTrailingAction}>
-      <BranchName href={`https://github.com/${repo}/tree/${selected.text}`} className={styles.BranchNameTransparent}>
+    <>
+      <BranchName href={`https://github.com/${repo}/tree/${selected.text}`}>
         {selected.text}
+        <BranchName.TrailingAction
+          icon={TriangleDownIcon}
+          aria-label="Change base branch"
+          ref={anchorRef}
+          onClick={() => setOpen(!open)}
+        />
       </BranchName>
       <SelectPanel
-        renderAnchor={anchorProps => (
-          <IconButton
-            icon={TriangleDownIcon}
-            aria-label="Change base branch"
-            variant="invisible"
-            size="small"
-            className={styles.TrailingActionButton}
-            {...anchorProps}
-          />
-        )}
+        renderAnchor={null}
+        anchorRef={anchorRef}
         placeholder="Find a branch..."
         open={open}
         onOpenChange={setOpen}
@@ -129,6 +122,37 @@ export const WithTrailingActionMenu = ({repo = 'primer/react'}: {repo: string})
         title="Change base branch"
         overlayProps={{width: 'medium'}}
       />
-    </span>
+    </>
+  )
+}
+
+export const KitchenSink = ({
+  branchName = 'fix/anchored-overlay-outside-top-autogrow',
+  repo = 'primer/react',
+}: {
+  branchName: string
+  repo: string
+}) => {
+  const [copied, setCopied] = React.useState(false)
+
+  const handleCopy = () => {
+    setCopied(true)
+    void navigator.clipboard.writeText(branchName)
+    announce('Copied!')
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+      <BranchName.LeadingVisual>
+        <GitBranchIcon />
+      </BranchName.LeadingVisual>
+      {branchName}
+      <BranchName.TrailingAction
+        icon={copied ? CheckIcon : CopyIcon}
+        aria-label="Copy branch name to clipboard"
+        onClick={handleCopy}
+      />
+    </BranchName>
   )
 }

packages/react/src/BranchName/BranchName.module.css

@@ -1,5 +1,6 @@
 .BranchName {
-  display: inline-block;
+  display: inline-flex;
+  align-items: center;
   padding: var(--base-size-2) var(--base-size-6);
   font-family: var(--fontStack-monospace);
   font-size: var(--text-body-size-small);
@@ -11,4 +12,63 @@
   &:is(:not(a)) {
     color: var(--fgColor-muted);
   }
+
+  [data-component='BranchName.LeadingVisual'] {
+    display: inline-flex;
+    align-items: center;
+    margin-inline-end: var(--base-size-4);
+  }
+}
+
+/* Container for BranchName with trailing actions */
+.BranchNameWithTrailingAction {
+  display: inline-flex;
+  align-items: stretch;
+
+  /* Create room for pseudo-border divider */
+  gap: var(--borderWidth-default);
+  flex-wrap: nowrap;
+  /* Moving the background to the container allows stacking the button hover background over it */
+  background-color: var(--bgColor-accent-muted);
+  border-radius: var(--borderRadius-medium);
+
+  [data-component='BranchName'] {
+    background-color: transparent;
+  }
+
+  [data-component='BranchName.TrailingAction'] {
+    display: inline-flex;
+    align-items: stretch;
+  }
+
+  [data-component='IconButton'] {
+    /* Make the size auto calculated based on icon size and padding */
+    height: auto;
+    width: auto;
+    padding: var(--base-size-2) var(--base-size-6);
+    position: relative;
+    align-items: center;
+
+    &:not(:disabled, [aria-disabled='true']) {
+      --button-invisible-iconColor-rest: var(--fgColor-link);
+    }
+
+    [data-component='Octicon'] {
+      /* Set icon size to text size to exactly match the branch name component */
+      height: var(--text-body-size-small);
+      width: var(--text-body-size-small);
+    }
+
+    /* Dividing line between button and name. */
+    &::before {
+      content: '';
+      position: absolute;
+      width: var(--borderWidth-default);
+      /* Position _between_ items (offsetting by width) to avoid overlapping with the real button border on hover/focus */
+      inset: var(--base-size-4) auto var(--base-size-4) calc(-1 * var(--borderWidth-default));
+      /* we want a divider/border but are using background color to make that happen */
+      /* stylelint-disable-next-line primer/colors */
+      background-color: var(--borderColor-accent-muted);
+    }
+  }
 }