Prefer visible folder children when deriving navigation indexes (#3451)

* Initial plan

* Add hidden folder navigation safeguards

* Finish hidden navigation index fix

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

src/Elastic.Documentation.Navigation/Isolated/Node/FolderNavigation.cs

@@ -32,7 +32,7 @@ public class FolderNavigation<TModel>(
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; } = parent;
 
 	/// <inheritdoc />
-	public bool Hidden { get; }
+	public bool Hidden { get; private set; }
 
 	/// <inheritdoc />
 	public int NavigationIndex { get; set; }
@@ -50,6 +50,7 @@ internal void SetNavigationItems(IReadOnlyCollection<INavigationItem> navigation
 	{
 		var indexNavigation = navigationItems.QueryIndex<TModel>(this, $"{FolderPath}/index.md", out navigationItems);
 		Index = indexNavigation;
+		Hidden = Index.Hidden;
 		// Include NavigationRoot.Id to ensure uniqueness across docsets in assembler builds
 		// (URLs alone aren't unique until path prefixes are applied by SiteNavigation)
 		Id = ShortId.Create(NavigationRoot.Id, Index.Url);

src/Elastic.Documentation.Navigation/Isolated/Node/TableOfContentsNavigation.cs

@@ -77,7 +77,7 @@ INavigationHomeProvider homeProvider
 	public INavigationHomeProvider HomeProvider { get; set; }
 
 	/// <inheritdoc />
-	public bool Hidden { get; }
+	public bool Hidden { get; private set; }
 
 	/// <inheritdoc />
 	public int NavigationIndex { get; set; }
@@ -104,6 +104,7 @@ internal void SetNavigationItems(IReadOnlyCollection<INavigationItem> navigation
 	{
 		var indexNavigation = navigationItems.QueryIndex<TModel>(this, $"{ParentPath}/index.md", out navigationItems);
 		Index = indexNavigation;
+		Hidden = Index.Hidden;
 		// Include NavigationRoot.Id to ensure uniqueness across docsets in assembler builds
 		Id = ShortId.Create(NavigationRoot.Id, Index.Url);
 		NavigationItems = navigationItems;

src/Elastic.Documentation.Navigation/NavigationItemExtensions.cs

@@ -16,16 +16,21 @@ this IReadOnlyCollection<INavigationItem> items, INodeNavigationItem<INavigation
 	)
 		where TModel : class, IDocumentationFile
 	{
-		var index = LookupIndex();
+		var index = LookupIndex(preferVisible: true);
+		index ??= LookupIndex(preferVisible: false);
+		ArgumentNullException.ThrowIfNull(index);
 
 		children = items.Except([index]).ToArray();
 
 		return index;
 
-		ILeafNavigationItem<TModel> LookupIndex()
+		ILeafNavigationItem<TModel>? LookupIndex(bool preferVisible)
 		{
 			foreach (var item in items)
 			{
+				if (preferVisible && item.Hidden)
+					continue;
+
 				// Check for the exact type match
 				if (item is ILeafNavigationItem<TModel> leaf)
 					return leaf;
@@ -35,6 +40,9 @@ ILeafNavigationItem<TModel> LookupIndex()
 					return nodeItem.Index;
 			}
 
+			if (preferVisible)
+				return null;
+
 			// If no index is found, throw an exception
 			throw new InvalidOperationException($"No index found for navigation node '{node.GetType().Name}' at path '{fallbackPath}'");
 		}

tests/Navigation.Tests/Isolation/DynamicUrlTests.cs

@@ -113,6 +113,58 @@ public void FolderWithoutIndexUsesFirstChildUrl()
 		folder!.Url.Should().Be("/guides/getting-started");
 	}
 
+	[Fact]
+	public void FolderWithoutIndexUsesFirstVisibleChildUrlWhenHiddenChildComesFirst()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - folder: guides
+		               children:
+		                 - hidden: autopilot.md
+		                 - file: getting-started.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext();
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+
+		var navigation = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+		var folder = navigation.NavigationItems.First().Should().BeOfType<FolderNavigation<IDocumentationFile>>().Subject;
+
+		folder.Hidden.Should().BeFalse();
+		folder.NavigationTitle.Should().Be("getting-started");
+		folder.Url.Should().Be("/guides/getting-started");
+		folder.NavigationItems.Should().ContainSingle().Which.Hidden.Should().BeTrue();
+	}
+
+	[Fact]
+	public void FolderWithoutIndexAndOnlyHiddenChildrenIsHidden()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - folder: guides
+		               children:
+		                 - hidden: autopilot.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext();
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+
+		var navigation = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+		var folder = navigation.NavigationItems.First().Should().BeOfType<FolderNavigation<IDocumentationFile>>().Subject;
+
+		folder.Hidden.Should().BeTrue();
+		folder.Index.Hidden.Should().BeTrue();
+		folder.NavigationItems.Should().BeEmpty();
+	}
+
 	[Fact]
 	public void FolderWithNestedChildren()
 	{