Breadcrumbs Upgrade: Added List system

[RayRedGoose]

Overview of made changes

Breadcrumbs component has been promoted to canvas-kit-react package because now it uses the same list system being developed for Tabs, ActionBar which provides the new overflow behavior based on utilizing useBreadcrumbsModel. Overflow is dynamic and calculated on the container width.

To archive this goal some Breadcrumbs API has been reviewed and the next changes have been made:

• Breadcrumbs has been promoted and now it lives in main react package
• Breadcrumbs.Nav has been removed and replaced by Breadcrumbs
• Breadcrumbs.Nav prop of aria-label has been removed to Breadcrumbs
• Breadcrumbs.CollapsibleList has been renamed to Breadcrumbs.List
• Breadcrumbs.ListItem has been renamed to Breadcrumbs.Item

🤖 All the above changes can be handled by running codemod

🙎‍♂️ The next changes will require manual changes:

• Handling Redirects
• Updated Overflow Behavior

Handling Redirects

onAction has been removed from Breadcrumbs.Item, so the way of redirection has been changed.

Breadcrumbs.Link defaults to redirecting with an href, which means the page will hard-redirect when the link is clicked. However, if you're in a single-page application (SPA) environment, you might want to use the internal SPA router instead. You can override that behavior with a custom onClick handler that blocks the default behavior of the event and passes along the link path to your SPA router. Most of our consumers use react-router-dom for managing SPA routing, so below is an example of how to do this in V5 and V6 of react-router-dom. Read more about moving from Router DOM v5 to v6

// React Router DOM V5 API
import {useHistory} from 'react-router-dom';
import {Breadcrumbs} from '@workday/canvas-kit-react/breadcrumbs';
...
const history = useHistory();
const handleClick = (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>, link?: string) => {
      event.preventDefault();
    // if no link is provided, default to the current path
    history.push(link || window.location.pathname);
}
return (
  <Breadcrumbs.Link href="/account" onClick={handleClick}>
    Account
  </Breadcrumbs.Link>
);

// React Router DOM V6 API
import {useNavigate} from 'react-router-dom';
import {Breadcrumbs} from '@workday/canvas-kit-react/breadcrumbs';
...
const navigate = useNavigate();
const handleClick = (event: React.MouseEvent<HTMLAnchorElement, MouseEvent>, link?: string) => {
      event.preventDefault();
    // if no link is provided, default to the current path
    navigate(link || window.location.pathname);
}
return (
  <Breadcrumbs.Link href="/account" onClick={handleClick}>
    Account
  </Breadcrumbs.Link>
);

Overflow behavior

As Breadcrumbs.CollapsibleList has been removed, all overflow functionality provided by this component has been removed too. Now overflow functionality is provided by List system and requires to switch to BreadcrumbsModel manually. In the end of this discussion you can find step-by-step instruction to switch to a new structure.

// v7 structure
import {Breadcrumbs} from '@workday/canvas-kit-preview-react/breadcrumbs';

export const OldCollapsibleList = () => {
  return (
    <Breadcrumbs.Nav aria-label="breadcrumb">
      <Breadcrumbs.CollapsibleList buttonAriaLabel="more links" maxWidth={300}>
        <Breadcrumbs.ListItem>
          <Breadcrumbs.Link href="/">Home</Breadcrumbs.Link>
        </Breadcrumbs.ListItem>
        <Breadcrumbs.ListItem>
          <Breadcrumbs.Link href="/menus">Menus</Breadcrumbs.Link>
        </Breadcrumbs.ListItem>
        <Breadcrumbs.ListItem>
          <Breadcrumbs.Link href="/lunch">Lunch</Breadcrumbs.Link>
        </Breadcrumbs.ListItem>
        <Breadcrumbs.ListItem>
          <Breadcrumbs.Link href="/small-plates-and-appetizers">
            Small Plates & Appetizers
          </Breadcrumbs.Link>
        </Breadcrumbs.ListItem>
        <Breadcrumbs.CurrentItem>Focaccia Genovese</Breadcrumbs.CurrentItem>
      </Breadcrumbs.CollapsibleList>
    </Breadcrumbs.Nav>
  );
};

// v8 structure
const NewOverflowList = () => {
  const [items] = React.useState([
    {id: '1', text: 'Home', link: '/'},
    {id: '2', text: 'Menus', link: '/menus'},
    {id: '3', text: 'Lunch', link: '/lunch'},
    {id: '4', text: 'Small Plates & Appetizers', link: '/small-plates-and-appetizers'},
    {id: '5', text: 'Focaccia Genovese'},
  ]);

  return (
    <Breadcrumbs items={items}>
      <Breadcrumbs.List overflowButton={<Breadcrumbs.OverflowButton aria-label="More links" />}>
	{item =>
	  item.link ? (
	    <Breadcrumbs.Item>
	      <Breadcrumbs.Link href={item.link}>{item.text}</Breadcrumbs.Link>
	    </Breadcrumbs.Item>
	  ) : (
	    <Breadcrumbs.CurrentItem>{item.text}</Breadcrumbs.CurrentItem>
	  )
	}
      </Breadcrumbs.List>
      <Breadcrumbs.Menu.Popper>
        <Breadcrumbs.Menu.Card>
	  <Breadcrumbs.Menu.List>
	    {(item: Breadcrumb) => (
		<Breadcrumbs.Menu.Item>{item.text}</Breadcrumbs.Menu.Item>
	    )}
	  </Breadcrumbs.Menu.List>
	</Breadcrumbs.Menu.Card>
      </Breadcrumbs.Menu.Popper>
    </Breadcrumbs>
  );
}

Manual transition to a new structure:

Step-by-step instruction:

1. Create array of breadcrumbs items based contains info about all your Breadcrumbs.ListItem, all objects inside array should contains an id property with the unique string value:

const items = [
  {id: '1', text: 'Home Link', link: '/'},
  {id: '2', text: 'Current Item'}
];

2. Pass an items array into Breadcrumbs component through items prop:

const items = [{...}];

<Breadcrumbs items={items}>
  // code inside
</Breadcrumbs>

or pass the created model with items:

const items = [{...}];
const model = useBreadcrumbsModel({items});
<Breadcrumbs model={model}>
  // code inside
</Breadcrumbs>

3. Rename Breadcrumbs.Nav to Breadcrumbs and Breadcrumbs.CollapsibleList to Breadcrumbs.List or if check it's renamed if you used codemod before it.

4. Remove all content inside Breadcrumbs.List and add function recreating all items from your items array (this structure is similar to .map() array prototype method callback fn):

{item =>
  item.link ? (
    <Breadcrumbs.Item>
      <Breadcrumbs.Link href={item.link}>{item.text}</Breadcrumbs.Link>
    </Breadcrumbs.Item>
  ) : (
    <Breadcrumbs.CurrentItem>{item.text}</Breadcrumbs.CurrentItem>
  )
}

5. After Breadcrumbs.List but inside Breadcrumbs add overflow menu component:

<Breadcrumbs.Menu.Popper>
  <Breadcrumbs.Menu.Card>
    <Breadcrumbs.Menu.List>
     {(item: Breadcrumb) => (
       <Breadcrumbs.Menu.Item>{item.text}</Breadcrumbs.Menu.Item>
     )}
    </Breadcrumbs.Menu.List>
  </Breadcrumbs.Menu.Card>
</Breadcrumbs.Menu.Popper>

6. Save and check if component works as expected