Skip to content

Dashboard v2: implement breadcrumbs #103294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: trunk
Choose a base branch
from
+48 −11
Open

Dashboard v2: implement breadcrumbs #103294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion client/dashboard/.eslintrc.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,9 @@ module.exports = {
'@automattic/components/*',
'!@automattic/components/src',
'@automattic/components/src/*',
'!@automattic/components/src/summary-button',
'!@automattic/components/src/core-badge',
'!@automattic/components/src/breadcrumbs',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clicking the breadcrumb items will trigger a page reload. This is because it's a regular link, not a router link. I don't have any good idea yet how to solve it. Need help from @Automattic/io.

How difficult is it to just create the breadcrumb links ourselves? In this case, it looks like there will only ever be a single breadcrumb link, looking at the designs, so this doesn't seem that complex to add a single {link} / above the header?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I honestly initially thought about that... but then why are we creating a full-blown <Breadcrumbs /> DS component if it's never going to be used beyond the above simple case? That thinking made me end up trying to come up with a more general breadcrumbs system 🥲

Even if we have to hardcode the router link, we will need to copy-paste the styles from the <Breadcrumbs /> component. Not sure if that's a good idea design-wise 🤔

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, if we're only ever going to add one link then we can remove that component eventually. I don't think we should necessarily import styles from Calypso components, we should focus on using @wordpress styles with limited customisation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, this is not what I anticipated; I thought the idea is to make use of the reusable DS components. I'll see what I can do next week; it's getting late for me 😄

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or I can try to pass something to the link's onClick props and see if I can properly call TanStack router navigation with it.

wp-calypso/packages/components/src/breadcrumbs/index.tsx

Line 45 in bb42801

<a href={ href } onClick={ onClick } className="a8c-components-breadcrumbs__item">

I'd love to get input from @ntsekouras as the component author 🙏

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apparently Breadcrumbs was created for the hosting dashboard, but I don't have more information than that, so ignore my comments for now.

Copy link
Member

@ntsekouras ntsekouras May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or I can try to pass something to the link's onClick props and see if I can properly call TanStack router navigation with it.

For start that what I'd try to do personally, just for now. Or it might had to do with the path (relative/full, etc..).

Breadcrumbs will be part of the PageHeader component, that will land soon. My plan was to implement what this PR does, after the merge of PageHeader and try to see if we can make it work with a tags, but if it can't, we'll add support in the Breadcrumbs component to pass the element we want instead of a ( in this case Link). This was mentioned in the Breadcrumbs PR already.

So, for me the important part here is to create the functionality to retrieve the proper breadcrumb items and for now we could just use directly a Link and not the Breadcrumbs if not possible.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened a PR for this: #103321

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see if I can properly call TanStack router navigation with it.

If you do want to shortcut #103321 you can implement the onClick handler like

export default function Breadcrumbs() {
	const matches = useMatches();
	const navigate = useNavigate();

	const items = [] as BreadcrumbItemProps[];

	let hasParent = false;
	matches.forEach( ( match ) => {
		if ( match.loaderData?.breadcrumbItemLabel || hasParent ) {
			items.push( {
				label: match.loaderData?.breadcrumbItemLabel || '',
				href: match.pathname,
				onClick: ( e ) => {
					e.preventDefault();
					navigate( { to: match.pathname } );
				},
			} );
			hasParent = true;
		}
	} );

	return <BreadcrumbsComponent items={ items } />;
}

'!@automattic/components/src/summary-button',
'!@automattic/dataviews',
// Please do not add exceptions unless agreed on
// with the #architecture group.
Expand Down
22 changes: 22 additions & 0 deletions client/dashboard/app/breadcrumbs/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import { Breadcrumbs as BreadcrumbsComponent } from '@automattic/components/src/breadcrumbs';
import { useMatches } from '@tanstack/react-router';
import type { BreadcrumbItemProps } from '@automattic/components/src/breadcrumbs/types';

export default function Breadcrumbs() {
const matches = useMatches();

const items = [] as BreadcrumbItemProps[];

let hasParent = false;
matches.forEach( ( match ) => {
if ( match.loaderData?.breadcrumbItemLabel || hasParent ) {
items.push( {
label: match.loaderData?.breadcrumbItemLabel || '',
href: match.pathname,
} );
hasParent = true;
}
} );

return <BreadcrumbsComponent items={ items } />;
}
19 changes: 11 additions & 8 deletions client/dashboard/app/router.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import {
redirect,
createLazyRoute,
} from '@tanstack/react-router';
import { __ } from '@wordpress/i18n';
import { fetchTwoStep } from '../data';
import NotFound from './404';
import UnknownError from './500';
Expand All @@ -22,6 +23,7 @@ import type { AppConfig } from './context';

interface RouteContext {
config?: AppConfig;
breadcrumbItemLabel?: string;
}

const rootRoute = createRootRoute( { component: Root } );
Expand Down Expand Up @@ -107,8 +109,12 @@ const sitePerformanceRoute = createRoute( {
const siteSettingsRoute = createRoute( {
getParentRoute: () => siteRoute,
path: 'settings',
loader: ( { params: { siteSlug } } ) =>
queryClient.ensureQueryData( siteSettingsQuery( siteSlug ) ),
loader: async ( { params: { siteSlug } } ) => {
await queryClient.ensureQueryData( siteSettingsQuery( siteSlug ) );
return {
breadcrumbItemLabel: __( 'Settings' ),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does this have to be in the loader? Can't it be added as route meta or something?

Copy link
Contributor Author

@fushar fushar May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It needs to call __(), so it can't be a static data. Also, I imagine other screens might have dynamic breadcrumb item label such as plugin name in the Plugins dashboard (it's the case now in v1 if you go to https://wordpress.com/plugins)

BTW as per docs, meta has been replaced with https://tanstack.com/router/latest/docs/framework/react/guide/static-route-data.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is my conclusion after spending a day reading the docs and consulting with AI 🥲 but I'm open if you have better ideas! This is literally my first project with TanStack stack.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

__() can be called anywhere, it doesn't have to be called at render time.

But if you really want, you could create a function that maps a route to a label:

function getRouteBreadcrumbLabel( route ) {
    switch ( route.path ) {
        case 'setting': return __( 'Settings' );
    }
}

The loader function doesn't seem meant for this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would that work with dynamic label such as plugins (as I mentioned above)

image

We will need to fetch some data first (e.g. in the loader) before being able to return the label.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you point me to the designs for this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The design is not available yet in v2 actually. I just wanted to prepare for this case in case we want to bring this pattern to v2 😬

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think yeah we can try to put that in staticData (formerly meta) first and try to figure out the dynamic case when it's actually needed in the design...

__() can be called anywhere, it doesn't have to be called at render time.

I was afraid the translation might not be ready yet when we construct the routing, but I'm happy to be wrong. I can try.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, imo we shouldn't think about use cases that might not exist. If for now a simple link with a slash works, then imo that's good for now

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was afraid the translation might not be ready yet when we construct the routing, but I'm happy to be wrong. I can try.

For @wordpress/i18n in GB, I don't think it matters, I'm not sure about Calypso. But if you want to be sure it could be a function that maps it instead that is called during render

};
},
} ).lazy( () =>
import( '../sites/settings' ).then( ( d ) =>
createLazyRoute( 'site-settings' )( {
Expand All @@ -118,10 +124,8 @@ const siteSettingsRoute = createRoute( {
);

const siteSettingsSubscriptionGiftingRoute = createRoute( {
getParentRoute: () => siteRoute,
path: 'settings/subscription-gifting',
loader: ( { params: { siteSlug } } ) =>
queryClient.ensureQueryData( siteSettingsQuery( siteSlug ) ),
getParentRoute: () => siteSettingsRoute,
path: 'subscription-gifting',
} ).lazy( () =>
import( '../sites/settings-subscription-gifting' ).then( ( d ) =>
createLazyRoute( 'site-settings-subscription-gifting' )( {
Expand Down Expand Up @@ -292,8 +296,7 @@ const createRouteTree = ( config: AppConfig ) => {
siteOverviewRoute,
siteDeploymentsRoute,
sitePerformanceRoute,
siteSettingsRoute,
siteSettingsSubscriptionGiftingRoute,
siteSettingsRoute.addChildren( [ siteSettingsSubscriptionGiftingRoute ] ),
] )
);
}
Expand Down
2 changes: 2 additions & 0 deletions client/dashboard/components/page-layout/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import {
__experimentalHeading as Heading,
__experimentalText as Text,
} from '@wordpress/components';
import Breadcrumbs from '../../app/breadcrumbs';
import './style.scss';

const sizes = {
Expand Down Expand Up @@ -31,6 +32,7 @@ function PageLayout( {
return (
<VStack spacing={ 8 } className="dashboard-page-layout" style={ sizes[ size ] }>
<VStack spacing={ 4 }>
<Breadcrumbs />
<HStack justify="space-between" alignment="center">
<Heading level={ 1 } style={ { flexShrink: 0 } }>
{ title }
Expand Down
13 changes: 11 additions & 2 deletions client/dashboard/sites/settings/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,33 @@
import { useQuery } from '@tanstack/react-query';
import { Outlet, useMatch, useMatches } from '@tanstack/react-router';
import {
__experimentalHeading as Heading,
__experimentalVStack as VStack,
Card,
} from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import { siteQuery, siteSettingsQuery } from '../../app/queries';
import { siteRoute } from '../../app/router';
import { siteSettingsRoute } from '../../app/router';
import PageLayout from '../../components/page-layout';
import SubscriptionGiftingSettingsSummary from '../settings-subscription-gifting/summary';

export default function SiteSettings() {
const { siteSlug } = siteRoute.useParams();
const { siteSlug } = siteSettingsRoute.useParams();
const { data: siteData } = useQuery( siteQuery( siteSlug ) );
const { data: settings } = useQuery( siteSettingsQuery( siteSlug ) );

const matches = useMatches();
const match = useMatch( { from: siteSettingsRoute.id } );

if ( ! siteData || ! settings ) {
return null;
}

const isExactMatch = match.id === matches[ matches.length - 1 ].id;
if ( ! isExactMatch ) {
return <Outlet />;
}

return (
<PageLayout title={ __( 'Settings' ) } size="small">
<Heading>{ __( 'General' ) }</Heading>
Expand Down
Loading