Admin UI: Add Navigation component and Page navigation slot

packages/admin-ui/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   `Page`: Add a `navigation` prop (`{ items, currentHref, components }`) for link-based navigation between sections, rendered in the page header ([#79746](https://github.com/WordPress/gutenberg/pull/79746)).
+
 ### Bug Fixes
 
 -   `Breadcrumbs`: reset the list item margin that wp-admin's `common.css` applies, which left the trail misaligned with the rest of the page header ([#81134](https://github.com/WordPress/gutenberg/pull/81134)).

packages/admin-ui/src/navigation/index.tsx

@@ -0,0 +1,92 @@
+import { __ } from '@wordpress/i18n';
+import { Link, Stack, Text } from '@wordpress/ui';
+import type { NavigationProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * Renders a horizontal list of links for navigating between the sections of a
+ * screen. The item whose `href` matches `currentHref` is marked with
+ * `aria-current="page"`.
+ *
+ * Internal to the package: configured through the `Page` `navigation` prop.
+ */
+export const Navigation = ( {
+	items,
+	currentHref,
+	ariaLabel = __( 'Sections' ),
+	components,
+	className,
+}: NavigationProps ) => {
+	if ( ! items.length ) {
+		return null;
+	}
+
+	const LinkComponent = components?.link;
+
+	if ( process.env.NODE_ENV !== 'production' ) {
+		const invalidItem = items.find(
+			( item ) => typeof item.href !== 'string'
+		);
+		if ( invalidItem ) {
+			throw new Error(
+				`Navigation: item "${ invalidItem.label }" is missing an \`href\` prop.`
+			);
+		}
+
+		const duplicate = items.find(
+			( item, index ) =>
+				items.findIndex( ( other ) => other.href === item.href ) !==
+				index
+		);
+		if ( duplicate ) {
+			throw new Error(
+				`Navigation: duplicate \`href\` "${ duplicate.href }". Each item must have a unique \`href\` so a single item receives \`aria-current="page"\`.`
+			);
+		}
+	}
+
+	return (
+		<nav aria-label={ ariaLabel } className={ className }>
+			{ /*
+			 * Disable reason: The `list` ARIA role is redundant but
+			 * Safari+VoiceOver won't announce the list otherwise.
+			 */
+			/* eslint-disable jsx-a11y/no-redundant-roles */ }
+			<Stack
+				render={ <ul role="list" /> }
+				direction="row"
+				align="center"
+				gap="md"
+				className={ styles.list }
+			>
+				{ items.map( ( item ) => (
+					<li key={ item.href } className={ styles.li }>
+						<Text
+							variant="body-md"
+							className={ styles.item }
+							render={
+								<Link
+									variant="unstyled"
+									href={ item.href }
+									aria-current={
+										item.href === currentHref
+											? 'page'
+											: undefined
+									}
+									render={
+										LinkComponent && <LinkComponent />
+									}
+								/>
+							}
+						>
+							{ item.label }
+						</Text>
+					</li>
+				) ) }
+			</Stack>
+			{ /* eslint-enable jsx-a11y/no-redundant-roles */ }
+		</nav>
+	);
+};
+
+export default Navigation;

packages/admin-ui/src/navigation/style.module.css

@@ -0,0 +1,44 @@
+.list {
+	/**
+	 * Give the scrollport room for the outset focus ring (outline width plus
+	 * offset), which the overflow clipping would otherwise cut off. The
+	 * negative margin cancels the padding out of the surrounding layout.
+	 */
+	--focus-ring-size: calc(2 * var(--wpds-border-width-focus));
+
+	list-style: none;
+	padding: var(--focus-ring-size);
+	margin: calc(-1 * var(--focus-ring-size));
+	/**
+	 * Scroll horizontally rather than wrap or shrink when items overflow.
+	 */
+	overflow-x: auto;
+	scroll-padding: var(--focus-ring-size);
+}
+
+.li {
+	flex-shrink: 0;
+}
+
+.item {
+	display: flex;
+	align-items: center;
+	/**
+	 * Meet the 44x44px pointer target size of WCAG 2.5.5 Target Size
+	 * (Enhanced). No design token maps to this accessibility constant.
+	 */
+	min-block-size: 44px;
+	min-inline-size: 44px;
+	color: var(--wpds-color-foreground-interactive-neutral-weak);
+	font-weight: var(--wpds-typography-font-weight-default);
+	text-decoration: none;
+}
+
+.item:hover {
+	color: var(--wpds-color-foreground-interactive-neutral-weak-active);
+}
+
+.item[aria-current="page"] {
+	color: var(--wpds-color-foreground-interactive-neutral-weak-active);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+}

packages/admin-ui/src/navigation/test/index.test.tsx

@@ -0,0 +1,191 @@
+import { render, screen } from '@testing-library/react';
+import { Navigation } from '..';
+
+describe( 'Navigation', () => {
+	describe( 'validation', () => {
+		it( 'should throw when an item is missing `href`', () => {
+			expect( () =>
+				render(
+					<Navigation
+						items={ [
+							{ label: 'Overview', href: '/overview' },
+							{ label: 'Products' } as never,
+						] }
+					/>
+				)
+			).toThrow( /item "Products" is missing an `href` prop/ );
+			expect( console ).toHaveErrored();
+		} );
+
+		it( 'should throw when two items share the same `href`', () => {
+			expect( () =>
+				render(
+					<Navigation
+						items={ [
+							{ label: 'Overview', href: '/overview' },
+							{ label: 'Duplicate', href: '/overview' },
+						] }
+					/>
+				)
+			).toThrow( /duplicate `href` "\/overview"/ );
+			expect( console ).toHaveErrored();
+		} );
+
+		it( 'should not throw when all items have `href`', () => {
+			expect( () =>
+				render(
+					<Navigation
+						items={ [
+							{ label: 'Overview', href: '/overview' },
+							{ label: 'Products', href: '/products' },
+						] }
+					/>
+				)
+			).not.toThrow();
+		} );
+
+		it( 'should not throw when items is empty', () => {
+			expect( () => render( <Navigation items={ [] } /> ) ).not.toThrow();
+		} );
+
+		it( 'should allow an empty string `href`', () => {
+			expect( () =>
+				render(
+					<Navigation
+						items={ [
+							{ label: 'Overview', href: '' },
+							{ label: 'Products', href: '/products' },
+						] }
+						currentHref=""
+					/>
+				)
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'rendering', () => {
+		it( 'should render nothing when items is empty', () => {
+			const { container } = render( <Navigation items={ [] } /> );
+			expect( container ).toBeEmptyDOMElement();
+		} );
+
+		it( 'should render inside a nav with a default accessible label', () => {
+			render(
+				<Navigation
+					items={ [ { label: 'Overview', href: '/overview' } ] }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'navigation', {
+					name: 'Sections',
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should use a custom `ariaLabel` when provided', () => {
+			render(
+				<Navigation
+					items={ [ { label: 'Overview', href: '/overview' } ] }
+					ariaLabel="Analytics sections"
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'navigation', {
+					name: 'Analytics sections',
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render each item as a link with its `href`', () => {
+			render(
+				<Navigation
+					items={ [
+						{ label: 'Overview', href: '/overview' },
+						{ label: 'Products', href: '/products' },
+					] }
+				/>
+			);
+
+			const links = screen.getAllByRole( 'link' );
+			expect( links ).toHaveLength( 2 );
+			expect( links[ 0 ] ).toHaveTextContent( 'Overview' );
+			expect( links[ 0 ] ).toHaveAttribute( 'href', '/overview' );
+			expect( links[ 1 ] ).toHaveTextContent( 'Products' );
+			expect( links[ 1 ] ).toHaveAttribute( 'href', '/products' );
+		} );
+
+		it( 'should mark the item matching `currentHref` with aria-current="page"', () => {
+			render(
+				<Navigation
+					items={ [
+						{ label: 'Overview', href: '/overview' },
+						{ label: 'Products', href: '/products' },
+					] }
+					currentHref="/overview"
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'link', { name: 'Overview' } )
+			).toHaveAttribute( 'aria-current', 'page' );
+			expect(
+				screen.getByRole( 'link', { name: 'Products' } )
+			).not.toHaveAttribute( 'aria-current' );
+		} );
+
+		it( 'should mark an empty string `href` as current when `currentHref` is empty', () => {
+			render(
+				<Navigation
+					items={ [
+						{ label: 'Overview', href: '' },
+						{ label: 'Products', href: '/products' },
+					] }
+					currentHref=""
+				/>
+			);
+
+			// Disable reason: A link with an empty `href` doesn't surface in
+			// the accessibility three via `getByRole` with `name`. In practice
+			// this would likely not be something we would recommend doing, but
+			// this test verifies the expected behavior of current link testing.
+			// eslint-disable-next-line testing-library/no-node-access
+			const overviewLink = screen.getByText( 'Overview' ).closest( 'a' );
+			expect( overviewLink ).toHaveAttribute( 'href', '' );
+			expect( overviewLink ).toHaveAttribute( 'aria-current', 'page' );
+		} );
+	} );
+
+	describe( 'components', () => {
+		it( 'should render items with the provided link component', () => {
+			const CustomLink = ( {
+				children,
+				...props
+			}: React.AnchorHTMLAttributes< HTMLAnchorElement > ) => (
+				<a data-custom="true" { ...props }>
+					{ children }
+				</a>
+			);
+
+			render(
+				<Navigation
+					items={ [
+						{ label: 'Overview', href: '/overview' },
+						{ label: 'Products', href: '/products' },
+					] }
+					currentHref="/overview"
+					components={ { link: CustomLink } }
+				/>
+			);
+
+			const link = screen.getByRole( 'link', { name: 'Overview' } );
+			expect( link ).toHaveAttribute( 'data-custom', 'true' );
+			expect( link ).toHaveAttribute( 'href', '/overview' );
+			expect( link ).toHaveAttribute( 'aria-current', 'page' );
+			expect(
+				screen.getByRole( 'link', { name: 'Products' } )
+			).toHaveAttribute( 'data-custom', 'true' );
+		} );
+	} );
+} );

packages/admin-ui/src/navigation/types.ts

@@ -0,0 +1,57 @@
+import { type AnchorHTMLAttributes, type ComponentType } from 'react';
+
+export interface NavigationItem {
+	/**
+	 * The label text for the navigation item.
+	 */
+	label: string;
+
+	/**
+	 * The URL the item links to.
+	 */
+	href: string;
+}
+
+export interface NavigationComponents {
+	/**
+	 * Component rendered in place of the default `<a>` for each item, e.g. a
+	 * client-side router link. It receives standard anchor attributes
+	 * (`href`, `aria-current`, `className`, `children`) and must forward
+	 * them to the element it renders.
+	 *
+	 * @default 'a'
+	 */
+	link?: ComponentType< AnchorHTMLAttributes< HTMLAnchorElement > >;
+}
+
+export interface NavigationProps {
+	/**
+	 * The navigation items to display.
+	 */
+	items: readonly NavigationItem[];
+
+	/**
+	 * The `href` of the current item. The matching item is rendered with
+	 * `aria-current="page"` and a distinct visual treatment.
+	 */
+	currentHref?: string;
+
+	/**
+	 * Accessible label for the navigation landmark. Give each navigation on a
+	 * screen a unique label, and omit the word "navigation" since the landmark
+	 * role already conveys it.
+	 *
+	 * @default 'Sections'
+	 */
+	ariaLabel?: string;
+
+	/**
+	 * Overrides for the elements the navigation renders.
+	 */
+	components?: NavigationComponents;
+
+	/**
+	 * Optional class name for the root element.
+	 */
+	className?: string;
+}