Refactor navigation internals to store navigation in the kernel

RELEASE_NOTES.md

@@ -11,10 +11,12 @@ This serves two purposes:
 
 ### Added
 - Added a new `\Hyde\Framework\Actions\PreBuildTasks\TransferMediaAssets` build task handle media assets transfers for site builds.
+- Added a new `NavItem::getLink()` method contain the previous `NavItem::getDestination()` logic, to return the link URL.
 
 ### Changed
 - Changed how the documentation search is generated, to be an `InMemoryPage` instead of a post-build task.
 - Media asset files are now copied using the new build task instead of the deprecated `BuildService::transferMediaAssets()` method.
+- The `NavItem::getDestination()` method now returns its `Route` instance if that is the destination type.
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -54,6 +56,14 @@ For more information, see https://github.com/hydephp/develop/pull/1498.
 
 ## Low impact
 
+### Navigation item changes
+
+The `NavItem::getDestination()` method now returns its `Route` instance if that is the destination type. This allows for deferring the route evaluation.
+
+If you have previously used this method directly and expected a string to be returned, you may need to adapt your code to handle the new return type.
+
+If you want to retain the previous state where a string is always returned, you can use the new `NavItem::getLink()` method instead, which will resolve the route immediately.
+
 ### New documentation search implementation
 
 As the new documentation search implementation brings changes to their code API you may need to adapt your code

packages/framework/resources/views/layouts/navigation.blade.php

@@ -1,5 +1,5 @@
 @php
-    $navigation = \Hyde\Framework\Features\Navigation\NavigationMenu::create();
+    $navigation = \Hyde\Hyde::navigation();
 @endphp
 
 <nav aria-label="Main navigation" id="main-navigation" class="flex flex-wrap items-center justify-between p-4 shadow-lg sm:shadow-xl md:shadow-none dark:bg-gray-800">

packages/framework/src/Foundation/Concerns/BootsHydeKernel.php

@@ -7,6 +7,7 @@
 use Hyde\Foundation\Kernel\FileCollection;
 use Hyde\Foundation\Kernel\PageCollection;
 use Hyde\Foundation\Kernel\RouteCollection;
+use Hyde\Framework\Features\Navigation\NavigationMenu;
 
 /**
  * @internal Single-use trait for the HydeKernel class.
@@ -58,6 +59,8 @@ public function boot(): void
             $callback($this);
         }
 
+        $this->navigation = NavigationMenu::create();
+
         $this->booting = false;
         $this->booted = true;
     }

packages/framework/src/Foundation/Concerns/ManagesHydeKernel.php

@@ -5,6 +5,7 @@
 namespace Hyde\Foundation\Concerns;
 
 use Hyde\Foundation\HydeKernel;
+use Hyde\Framework\Features\Navigation\NavigationMenu;
 
 use function ltrim;
 use function rtrim;
@@ -71,6 +72,13 @@ public function getMediaOutputDirectory(): string
         return ltrim($this->getMediaDirectory(), '_');
     }
 
+    public function navigation(): NavigationMenu
+    {
+        $this->needsToBeBooted();
+
+        return $this->navigation;
+    }
+
     protected function normalizeSourcePath(string $outputDirectory): string
     {
         return $this->pathToRelative(rtrim($outputDirectory, '/\\'));

packages/framework/src/Foundation/HydeKernel.php

@@ -11,6 +11,7 @@
 use Hyde\Foundation\Kernel\PageCollection;
 use Hyde\Foundation\Kernel\RouteCollection;
 use Hyde\Support\Contracts\SerializableContract;
+use Hyde\Framework\Features\Navigation\NavigationMenu;
 use Hyde\Support\Concerns\Serializable;
 use Illuminate\Support\Traits\Macroable;
 
@@ -65,6 +66,8 @@ class HydeKernel implements SerializableContract
     protected PageCollection $pages;
     protected RouteCollection $routes;
 
+    protected NavigationMenu $navigation;
+
     protected bool $booted = false;
 
     /** @var array<class-string<\Hyde\Foundation\Concerns\HydeExtension>, \Hyde\Foundation\Concerns\HydeExtension> */

packages/framework/src/Framework/Features/Navigation/NavItem.php

@@ -20,7 +20,7 @@
  */
 class NavItem implements Stringable
 {
-    public readonly string $destination;
+    public readonly Route|string $destination;
     public readonly string $label;
     public readonly int $priority;
     public readonly ?string $group;
@@ -30,7 +30,7 @@ class NavItem implements Stringable
      */
     public function __construct(Route|string $destination, string $label, int $priority = 500, ?string $group = null)
     {
-        $this->destination = (string) $destination;
+        $this->destination = $destination;
         $this->label = $label;
         $this->priority = $priority;
         $this->group = $group;
@@ -42,7 +42,7 @@ public function __construct(Route|string $destination, string $label, int $prior
     public static function fromRoute(Route $route, ?string $label = null, ?int $priority = null, ?string $group = null): static
     {
         return new static(
-            $route->getLink(),
+            $route,
             $label ?? $route->getPage()->navigationMenuLabel(),
             $priority ?? $route->getPage()->navigationMenuPriority(),
             $group ?? static::getRouteGroup($route),
@@ -74,6 +74,17 @@ public static function forRoute(Route|string $route, ?string $label = null, ?int
      * Resolve a link to the navigation item.
      */
     public function __toString(): string
+    {
+        return (string) $this->destination;
+    }
+
+    /**
+     * Get the destination of the navigation item.
+     *
+     * If the navigation item is an external link, this will return the link as is,
+     * if it's for a route, the route instance will be returned.
+     */
+    public function getDestination(): Route|string
     {
         return $this->destination;
     }
@@ -82,11 +93,11 @@ public function __toString(): string
      * Get the destination link of the navigation item.
      *
      * If the navigation item is an external link, this will return the link as is,
-     * if it's for a route, a resolved relative link will be returned.
+     * if it's for a route, the route's resolved link will be returned.
      */
-    public function getDestination(): string
+    public function getLink(): string
     {
-        return $this->destination;
+        return (string) $this->destination;
     }
 
     /**
@@ -120,7 +131,7 @@ public function getGroup(): ?string
      */
     public function isCurrent(): bool
     {
-        return Hyde::currentRoute()->getLink() === $this->destination;
+        return Hyde::currentRoute()->getLink() === (string) $this->destination;
     }
 
     protected static function getRouteGroup(Route $route): ?string

packages/framework/src/Hyde.php

@@ -10,6 +10,7 @@
 use Hyde\Foundation\Kernel\Filesystem;
 use Hyde\Foundation\Kernel\PageCollection;
 use Hyde\Foundation\Kernel\RouteCollection;
+use Hyde\Framework\Features\Navigation\NavigationMenu;
 use Hyde\Pages\Concerns\HydePage;
 use Hyde\Support\Models\Route;
 use Hyde\Support\Filesystem\SourceFile;
@@ -50,6 +51,7 @@
  * @method static string getMediaDirectory()
  * @method static string getMediaOutputDirectory()
  * @method static Features features()
+ * @method static NavigationMenu navigation()
  * @method static FileCollection<SourceFile> files()
  * @method static PageCollection<HydePage> pages()
  * @method static RouteCollection<Route> routes()

packages/framework/tests/Feature/HydeKernelTest.php

@@ -24,6 +24,7 @@
 use Hyde\Testing\TestCase;
 use Illuminate\Support\Facades\Config;
 use Illuminate\Support\HtmlString;
+use Hyde\Framework\Features\Navigation\NavigationMenu;
 
 /**
  * This test class runs high-level tests on the HydeKernel class,
@@ -79,6 +80,11 @@ public function test_has_feature_helper_calls_method_on_features_class()
         $this->assertSame(Features::enabled('foo'), Hyde::hasFeature('foo'));
     }
 
+    public function test_has_navigation_helper_returns_site_navigation_instance()
+    {
+        $this->assertInstanceOf(NavigationMenu::class, Hyde::navigation());
+    }
+
     public function test_current_page_helper_returns_current_page_name()
     {
         Render::share('routeKey', 'foo');

packages/framework/tests/Unit/NavItemTest.php

@@ -43,13 +43,21 @@ public function test__construct()
         $route = new Route(new MarkdownPage());
         $item = new NavItem($route, 'Test', 500);
 
-        $this->assertSame($route->getLink(), $item->destination);
+        $this->assertSame($route, $item->destination);
     }
 
     public function testGetDestination()
+    {
+        $route = new Route(new MarkdownPage());
+        $item = new NavItem($route, 'Test', 500);
+
+        $this->assertSame($route, $item->getDestination());
+    }
+
+    public function testGetLink()
     {
         $navItem = new NavItem(new Route(new InMemoryPage('foo')), 'Page', 500);
-        $this->assertSame('foo.html', $navItem->getDestination());
+        $this->assertSame('foo.html', $navItem->getLink());
     }
 
     public function testGetLabel()
@@ -75,7 +83,7 @@ public function testFromRoute()
         $route = new Route(new MarkdownPage());
         $item = NavItem::fromRoute($route);
 
-        $this->assertSame($route->getLink(), $item->destination);
+        $this->assertSame($route, $item->destination);
     }
 
     public function test__toString()
@@ -104,7 +112,7 @@ public function testForRoute()
         $route = Routes::get('404');
         $item = NavItem::forRoute($route, 'foo');
 
-        $this->assertSame($route->getLink(), $item->destination);
+        $this->assertSame($route, $item->destination);
         $this->assertSame('foo', $item->label);
         $this->assertSame(999, $item->priority);
     }
@@ -114,7 +122,7 @@ public function testForIndexRoute()
         $route = Routes::get('index');
         $item = NavItem::forRoute($route, 'foo');
 
-        $this->assertSame($route->getLink(), $item->destination);
+        $this->assertSame($route, $item->destination);
         $this->assertSame('foo', $item->label);
         $this->assertSame(0, $item->priority);
     }