Navigation: Soft deprecate component

packages/components/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Deprecation
+
+-   `Navigation`: Soft deprecate component ([#59182](https://github.com/WordPress/gutenberg/pull/59182)).
+
 ### Enhancements
 
 -   `ExternalLink`: Use unicode arrow instead of svg icon ([#60255](https://github.com/WordPress/gutenberg/pull/60255)).

packages/components/src/navigation/README.md

@@ -1,5 +1,9 @@
 # Navigation
 
+<div class="callout callout-alert">
+This component is deprecated. Consider using `Navigator` instead.
+</div>
+
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>

packages/components/src/navigation/back-button/index.tsx

@@ -64,6 +64,9 @@ function UnforwardedNavigationBackButton(
 	);
 }
 
+/**
+ * @deprecated Use `Navigator` instead.
+ */
 export const NavigationBackButton = forwardRef(
 	UnforwardedNavigationBackButton
 );

packages/components/src/navigation/group/index.tsx

@@ -19,6 +19,9 @@ import type { NavigationGroupProps } from '../types';
 
 let uniqueId = 0;
 
+/**
+ * @deprecated Use `Navigator` instead.
+ */
 export function NavigationGroup( {
 	children,
 	className,

packages/components/src/navigation/index.tsx

@@ -28,6 +28,8 @@ const noop = () => {};
 /**
  * Render a navigation list with optional groupings and hierarchy.
  *
+ * @deprecated Use `Navigator` instead.
+ *
  * ```jsx
  * import {
  *   __experimentalNavigation as Navigation,

packages/components/src/navigation/item/index.tsx

@@ -22,6 +22,9 @@ import type { NavigationItemProps } from '../types';
 
 const noop = () => {};
 
+/**
+ * @deprecated Use `Navigator` instead.
+ */
 export function NavigationItem( props: NavigationItemProps ) {
 	const {
 		badge,

packages/components/src/navigation/menu/index.tsx

@@ -23,6 +23,9 @@ import { MenuUI } from '../styles/navigation-styles';
 
 import type { NavigationMenuProps } from '../types';
 
+/**
+ * @deprecated Use `Navigator` instead.
+ */
 export function NavigationMenu( props: NavigationMenuProps ) {
 	const {
 		backButtonLabel,

packages/components/src/navigation/stories/index.story.tsx

@@ -19,8 +19,14 @@ import { MoreExamplesStory } from './utils/more-examples';
 import { HideIfEmptyStory } from './utils/hide-if-empty';
 import './style.css';
 
+/**
+ * Render a navigation list with optional groupings and hierarchy.
+ *
+ * This component is deprecated. Consider using `Navigator` instead.
+ */
 const meta: Meta< typeof Navigation > = {
-	title: 'Components (Experimental)/Navigation',
+	title: 'Components (Deprecated)/Navigation',
+	id: 'components-navigation',
 	component: Navigation,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170

storybook/manager-head.html

@@ -1,10 +1,19 @@
 <script>
 	( function redirectIfStoryMoved() {
+		const PREVIOUSLY_EXPERIMENTAL_COMPONENTS = [ 'navigation' ];
 		const REDIRECTS = [
 			{
 				from: /\/components-deprecated-/,
 				to: '/components-',
 			},
+			{
+				from: new RegExp(
+					`\/components-experimental-(?=${ PREVIOUSLY_EXPERIMENTAL_COMPONENTS.map(
+						( str ) => `${ str }\\b`
+					).join( '|' ) })`
+				),
+				to: '/components-',
+			},
 		];
 
 		const params = new URLSearchParams( window.location.search );