From b750c2be81807c9a4d0899e4c2630797c67122b9 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Sat, 17 Feb 2024 19:39:19 +0900
Subject: [PATCH 1/4] Navigation: Soft deprecate component

---
 packages/components/src/navigation/README.md               | 4 ++++
 packages/components/src/navigation/back-button/index.tsx   | 3 +++
 packages/components/src/navigation/group/index.tsx         | 3 +++
 packages/components/src/navigation/index.tsx               | 2 ++
 packages/components/src/navigation/item/index.tsx          | 3 +++
 packages/components/src/navigation/menu/index.tsx          | 3 +++
 packages/components/src/navigation/stories/index.story.tsx | 3 ++-
 7 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/navigation/README.md b/packages/components/src/navigation/README.md
index 3a1fa992611b62..b294eb78331eef 100644
--- a/packages/components/src/navigation/README.md
+++ b/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>
diff --git a/packages/components/src/navigation/back-button/index.tsx b/packages/components/src/navigation/back-button/index.tsx
index 182faa8773726d..f1fb79ae40d484 100644
--- a/packages/components/src/navigation/back-button/index.tsx
+++ b/packages/components/src/navigation/back-button/index.tsx
@@ -64,6 +64,9 @@ function UnforwardedNavigationBackButton(
 	);
 }
 
+/**
+ * @deprecated Use `Navigator` instead.
+ */
 export const NavigationBackButton = forwardRef(
 	UnforwardedNavigationBackButton
 );
diff --git a/packages/components/src/navigation/group/index.tsx b/packages/components/src/navigation/group/index.tsx
index cd91fb97365d26..60febcf7644569 100644
--- a/packages/components/src/navigation/group/index.tsx
+++ b/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,
diff --git a/packages/components/src/navigation/index.tsx b/packages/components/src/navigation/index.tsx
index dfc1b26cb33ad0..9ccd4f46e5f182 100644
--- a/packages/components/src/navigation/index.tsx
+++ b/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,
diff --git a/packages/components/src/navigation/item/index.tsx b/packages/components/src/navigation/item/index.tsx
index 2fd1aebefcbbac..d234ed1a549b59 100644
--- a/packages/components/src/navigation/item/index.tsx
+++ b/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,
diff --git a/packages/components/src/navigation/menu/index.tsx b/packages/components/src/navigation/menu/index.tsx
index b001bd0fa0f3d8..8fcddf3faddb9e 100644
--- a/packages/components/src/navigation/menu/index.tsx
+++ b/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,
diff --git a/packages/components/src/navigation/stories/index.story.tsx b/packages/components/src/navigation/stories/index.story.tsx
index e0a3f1e1397576..bf8f77b6d130cb 100644
--- a/packages/components/src/navigation/stories/index.story.tsx
+++ b/packages/components/src/navigation/stories/index.story.tsx
@@ -20,7 +20,8 @@ import { HideIfEmptyStory } from './utils/hide-if-empty';
 import './style.css';
 
 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

From 8bd7063041483e499a7c5b6c6e21c3c2e915523d Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Fri, 12 Apr 2024 22:44:53 +0900
Subject: [PATCH 2/4] Set up redirect

---
 storybook/manager-head.html | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/storybook/manager-head.html b/storybook/manager-head.html
index 21ee902c02a36d..629f06bf98edf9 100644
--- a/storybook/manager-head.html
+++ b/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 );

From 18c86afabcc194dcf4d228a0687f6ccd7354c3b9 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Fri, 12 Apr 2024 22:43:47 +0900
Subject: [PATCH 3/4] Add deprecation notice in Storybook

---
 packages/components/src/navigation/stories/index.story.tsx | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/components/src/navigation/stories/index.story.tsx b/packages/components/src/navigation/stories/index.story.tsx
index bf8f77b6d130cb..2f09ace29f16e5 100644
--- a/packages/components/src/navigation/stories/index.story.tsx
+++ b/packages/components/src/navigation/stories/index.story.tsx
@@ -19,6 +19,11 @@ 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 (Deprecated)/Navigation',
 	id: 'components-navigation',

From 6f2bced232614028960f0fb1b0e1aeb648dbf301 Mon Sep 17 00:00:00 2001
From: Lena Morita <lena@jaguchi.com>
Date: Fri, 12 Apr 2024 22:58:15 +0900
Subject: [PATCH 4/4] Add changelog

---
 packages/components/CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index 63ec961b80f3c2..5ec6853128c31c 100644
--- a/packages/components/CHANGELOG.md
+++ b/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)).