Breadcrumbs : Add overflow menu for responsive behavior

.changeset/eighty-queens-tap.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+Breadcrumbs : Add overflow menu for responsive behavior

packages/react/src/Breadcrumbs/Breadcrumbs.docs.json

@@ -14,19 +14,27 @@
       "name": "className",
       "type": "string",
       "required": false,
-      "description": "",
+      "description": "Additional CSS class names to apply to the breadcrumbs container",
       "defaultValue": ""
     },
     {
       "name": "children",
       "type": "Breadcrumbs.Item[]",
       "defaultValue": "",
-      "description": ""
+      "description": "Breadcrumb items to render. Each item should be a Breadcrumbs.Item component."
+    },
+    {
+      "name": "overflow",
+      "type": "'wrap' | 'menu' | 'menu-with-root'",
+      "required": false,
+      "description": "How to handle overflow when breadcrumbs don't fit in the container. 'wrap' allows items to wrap to new lines. 'menu' collapses items into an overflow menu. 'menu-with-root' also collapses items into an overflow menu but includes the root (first) breadcrumb in the menu so only the last items remain visible.",
+      "defaultValue": "'wrap'"
     },
     {
       "name": "sx",
       "type": "SystemStyleObject",
-      "deprecated": true
+      "deprecated": true,
+      "description": "System styles (deprecated, use CSS classes instead)"
     }
   ],
   "subcomponents": [
@@ -37,7 +45,7 @@
           "name": "selected",
           "type": "boolean",
           "defaultValue": "false",
-          "description": "Whether this item represents the current page"
+          "description": "Whether this item represents the current page. Sets aria-current='page' for accessibility."
         },
         {
           "name": "to",
@@ -46,6 +54,18 @@
           "description": "Used when the item is rendered using a component like React Router's `Link`. The path to navigate to.",
           "defaultValue": ""
         },
+        {
+          "name": "href",
+          "type": "string",
+          "required": false,
+          "description": "The URL that the breadcrumb item links to. Used with regular anchor elements."
+        },
+        {
+          "name": "children",
+          "type": "React.ReactNode",
+          "required": true,
+          "description": "The content to display inside the breadcrumb item, typically text."
+        },
         {
           "name": "ref",
           "type": "React.RefObject<HTMLAnchorElement>"

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

@@ -0,0 +1,207 @@
+import type {Meta} from '@storybook/react-vite'
+import type React from 'react'
+import {useState} from 'react'
+import type {ComponentProps} from '../utils/types'
+import Breadcrumbs from './Breadcrumbs'
+import TextInput from '../TextInput'
+
+export default {
+  title: 'Components/Breadcrumbs/Features',
+  component: Breadcrumbs,
+} as Meta<ComponentProps<typeof Breadcrumbs>>
+
+export const OverflowWrap = () => (
+  <Breadcrumbs overflow="wrap">
+    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Item</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Details</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#" selected>
+      Current Page
+    </Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+
+export const OverflowMenu = () => (
+  <Breadcrumbs overflow="menu">
+    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Item</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Details</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#" selected>
+      Current Page
+    </Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+
+export const OverflowMenuShowRoot = () => (
+  <Breadcrumbs overflow="menu-with-root">
+    <Breadcrumbs.Item href="#">github</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Teams</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Engineering</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">core-productivity</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">collaboration-workflows-flex</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#" selected>
+      global-navigation-reviewers
+    </Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+
+export const OverflowMenuNarrowContainer = () => (
+  <div style={{width: '350px', border: '1px solid #ccc', padding: '8px'}}>
+    <Breadcrumbs overflow="menu">
+      <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
+      <Breadcrumbs.Item href="#" selected>
+        Current Page
+      </Breadcrumbs.Item>
+    </Breadcrumbs>
+  </div>
+)
+
+// Wrapper components to test that BreadcrumbsItem works when wrapped
+const StyledWrapper = ({children}: {children: React.ReactNode}) => (
+  <span style={{padding: '2px', border: '1px dotted #999'}}>{children}</span>
+)
+
+const ConditionalWrapper = ({children, condition}: {children: React.ReactNode; condition: boolean}) => {
+  return condition ? <strong>{children}</strong> : <>{children}</>
+}
+
+const DataAttributeWrapper = ({children}: {children: React.ReactNode}) => (
+  <span data-testid="wrapper" className="custom-wrapper">
+    {children}
+  </span>
+)
+
+export const WrappedBreadcrumbItemsWithOverflow = () => (
+  <Breadcrumbs overflow="menu">
+    <StyledWrapper>
+      <Breadcrumbs.Item href="#">Wrapped Home</Breadcrumbs.Item>
+    </StyledWrapper>
+    <ConditionalWrapper condition={false}>
+      <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item>
+    </ConditionalWrapper>
+    <DataAttributeWrapper>
+      <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item>
+    </DataAttributeWrapper>
+    <StyledWrapper>
+      <Breadcrumbs.Item href="#">Subcategory</Breadcrumbs.Item>
+    </StyledWrapper>
+    <ConditionalWrapper condition={true}>
+      <Breadcrumbs.Item href="#">Item</Breadcrumbs.Item>
+    </ConditionalWrapper>
+    <DataAttributeWrapper>
+      <Breadcrumbs.Item href="#">Details</Breadcrumbs.Item>
+    </DataAttributeWrapper>
+    <Breadcrumbs.Item href="#" selected>
+      Current Page
+    </Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+
+export const WithEditableNameInput = () => (
+  <Breadcrumbs>
+    <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Documents</Breadcrumbs.Item>
+    <Breadcrumbs.Item href="#">Project Alpha</Breadcrumbs.Item>
+    <Breadcrumbs.Item>
+      <TextInput
+        defaultValue="Untitled Document"
+        size="small"
+        sx={{
+          minWidth: '120px',
+          maxWidth: '180px',
+          fontSize: 'inherit',
+          border: '1px dashed var(--borderColor-muted)',
+          '&:focus': {
+            border: '1px solid var(--borderColor-accent-emphasis)',
+          },
+        }}
+        aria-label="Edit document name"
+      />
+    </Breadcrumbs.Item>
+  </Breadcrumbs>
+)
+
+export const DynamicChildren = () => {
+  const [items, setItems] = useState([
+    {id: 1, href: '#', name: 'Home'},
+    {id: 2, href: '#', name: 'Docs'},
+    {id: 3, href: '#', name: 'Components'},
+  ])
+
+  const addItem = () => {
+    const newId = Math.max(...items.map(item => item.id)) + 1
+    const names = ['Advanced', 'Examples', 'Guides', 'API', 'Tutorials', 'Reference']
+    const randomName = names[Math.floor(Math.random() * names.length)]
+    setItems([...items, {id: newId, href: '#', name: `${randomName}-${newId}`}])
+  }
+
+  const removeItem = () => {
+    if (items.length > 1) {
+      setItems(items.slice(0, -1))
+    }
+  }
+
+  const addMultipleItems = () => {
+    const newItems = [
+      {id: Date.now() + 1, href: '#', name: 'Category'},
+      {id: Date.now() + 2, href: '#', name: 'Subcategory'},
+      {id: Date.now() + 3, href: '#', name: 'Item'},
+      {id: Date.now() + 4, href: '#', name: 'Details'},
+      {id: Date.now() + 5, href: '#', name: 'Specifications'},
+    ]
+    setItems([...items, ...newItems])
+  }
+
+  const reset = () => {
+    setItems([
+      {id: 1, href: '#', name: 'Home'},
+      {id: 2, href: '#', name: 'Docs'},
+      {id: 3, href: '#', name: 'Components'},
+    ])
+  }
+
+  return (
+    <div style={{display: 'flex', flexDirection: 'column', gap: '16px'}}>
+      <div style={{display: 'flex', gap: '8px', marginBottom: '16px'}}>
+        <button type="button" onClick={addItem} style={{padding: '4px 8px'}}>
+          Add Item
+        </button>
+        <button type="button" onClick={removeItem} style={{padding: '4px 8px'}}>
+          Remove Item
+        </button>
+        <button type="button" onClick={addMultipleItems} style={{padding: '4px 8px'}}>
+          Add Many Items
+        </button>
+        <button type="button" onClick={reset} style={{padding: '4px 8px'}}>
+          Reset
+        </button>
+      </div>
+
+      <div>
+        <h4 id="dynamic-breadcrumbs-heading" style={{margin: '0 0 8px 0'}}>
+          Dynamic breadcrumbs
+        </h4>
+        <Breadcrumbs overflow="menu-with-root">
+          {items.map((item, index) => (
+            <Breadcrumbs.Item key={item.id} href={item.href} selected={index === items.length - 1}>
+              {item.name}
+            </Breadcrumbs.Item>
+          ))}
+        </Breadcrumbs>
+      </div>
+
+      <div style={{marginTop: '16px', fontSize: '12px'}}>
+        Current items: {items.length} | Try adding/removing items to see how overflow behavior changes
+      </div>
+    </div>
+  )
+}

packages/react/src/Breadcrumbs/Breadcrumbs.module.css

@@ -1,6 +1,7 @@
 .BreadcrumbsBase {
   display: flex;
   justify-content: space-between;
+  width: 100%;
 }
 
 .BreadcrumbsList {
@@ -9,10 +10,100 @@
   margin-bottom: 0;
 }
 
-.ItemWrapper {
+[data-overflow='menu'] .BreadcrumbsList,
+[data-overflow='menu-with-root'] .BreadcrumbsList {
+  white-space: nowrap;
+  display: flex;
+  flex-direction: row;
+}
+
+.BreadcrumbsItem {
+  display: inline-grid;
+  grid-auto-flow: column;
+  align-items: center;
+  flex: 0 99999 auto;
+  min-width: auto;
+  font-size: var(--text-body-size-medium);
+  white-space: nowrap;
+  list-style: none;
+
+  &:first-child {
+    margin-left: 0;
+  }
+
+  &:last-child {
+    .ItemSeparator {
+      display: none;
+    }
+  }
+}
+
+[data-overflow='menu'] .Item,
+[data-overflow='menu-with-root'] .Item {
   display: inline-block;
   font-size: var(--text-body-size-medium);
+  color: var(--fgColor-default);
+  text-decoration: none;
+  padding-inline: var(--base-size-6);
+  padding-block: var(--base-size-4);
+  border-radius: var(--borderRadius-medium);
+
+  &:hover {
+    background: var(--control-transparent-bgColor-hover);
+    text-decoration: none;
+  }
+
+  &:focus {
+    @mixin focusOutline;
+  }
+}
+
+.MenuDetails {
+  position: relative;
+  display: inline-block;
+}
+
+summary {
+  list-style: none;
+  cursor: pointer;
+  outline: none;
+}
+
+summary::-webkit-details-marker {
+  display: none;
+}
+
+.MenuOverlay {
+  position: absolute;
+  z-index: 1;
+  box-shadow: var(--shadow-resting-small);
+  border-radius: var(--borderRadius-large);
+  background-color: var(--overlay-bgColor);
+  list-style: none;
+  min-width: var(--overlay-width-xsmall);
+  max-height: 100vh;
+  max-width: var(--overlay-width-small);
+  overflow: hidden;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .MenuOverlay {
+    animation: overlay-appear 200ms cubic-bezier(0.33, 1, 0.68, 1);
+  }
+}
+
+.ItemSeparator {
+  color: var(--fgColor-muted);
+  display: flex;
+  align-self: center;
+  justify-content: center;
   white-space: nowrap;
+  user-select: none;
+}
+
+.ItemWrapper {
+  display: inline-block;
+  font-size: var(--text-body-size-medium);
   list-style: none;
 
   &::after {

packages/react/src/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -1,4 +1,5 @@
 import type {Meta} from '@storybook/react-vite'
+import React from 'react'
 import type {ComponentProps} from '../utils/types'
 import Breadcrumbs from './Breadcrumbs'