Breaking: Rename class NavItem to NavigationItem

RELEASE_NOTES.md

@@ -12,15 +12,15 @@ 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 `ExternalRoute` class to represent external routes.
-- Added a new `NavItem::getLink()` method contain the previous `NavItem::getDestination()` logic, to return the link URL.
+- Added a new `NavigationItem::getLink()` method contain the previous `NavigationItem::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.
 - Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
 - Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
-- Breaking: The `NavItem` class now always stores the destination as a `Route` instance.
-- Breaking: The `NavItem::getDestination()` method now returns its `Route` instance.
+- Breaking: The `NavigationItem` class now always stores the destination as a `Route` instance.
+- Breaking: The `NavigationItem::getDestination()` method now returns its `Route` instance.
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -63,11 +63,11 @@ For more information, see https://github.com/hydephp/develop/pull/1498.
 
 ### Navigation item changes
 
-The `NavItem::getDestination()` method now returns its `Route` instance. This allows for deferring the route evaluation.
+The `NavigationItem::getDestination()` method now returns its `Route` instance. 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.
+If you want to retain the previous state where a string is always returned, you can use the new `NavigationItem::getLink()` method instead, which will resolve the route immediately.
 
 ### HTML ID changes
 

config/hyde.php

@@ -350,7 +350,7 @@
         // To get started quickly, you can uncomment the defaults here.
         // See the documentation link above for more information.
         'custom' => [
-            // NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+            // NavigationItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
         ],
 
         // How should pages in subdirectories be displayed in the menu?

docs/digging-deeper/navigation.md

@@ -230,18 +230,18 @@ To remove items from being automatically added, simply add the page's route key
 
 ### Adding Custom Navigation Menu Links
 
-You can easily add custom navigation menu links similar to how we add Authors. Simply add a `NavItem` model to the `navigation.custom` array.
+You can easily add custom navigation menu links similar to how we add Authors. Simply add a `NavigationItem` model to the `navigation.custom` array.
 
-When linking to an external site, you should use the `NavItem::forLink()` method facade. The first two arguments are the
+When linking to an external site, you should use the `NavigationItem::forLink()` method facade. The first two arguments are the
 destination and label, both required. The third argument is the priority, which is optional, and defaults to `500`.
 
 ```php
 // filepath config/hyde.php
-use Hyde\Framework\Features\Navigation\NavItem;
+use Hyde\Framework\Features\Navigation\NavigationItem;
 
 'navigation' => [
     'custom' => [
-        NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+        NavigationItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
     ]
 ]
 ```
@@ -314,14 +314,14 @@ use Hyde\Framework\Features\Navigation\BaseNavigationMenu;
 Within the `BaseNavigationMenu` class, you will find the main logic for how the menus are generated,
 while the child implementations contain the extra logic tailored for their specific use cases.
 
-All the navigation menus store the menu items in their `$items` array containing instances of the `NavItem` class.
+All the navigation menus store the menu items in their `$items` array containing instances of the `NavigationItem` class.
 
-The `NavItem` class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu.
-Dropdowns are represented by `DropdownNavItem` instances, which extend the `NavItem` class and contain an array of additional `NavItem` instances.
+The `NavigationItem` class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu.
+Dropdowns are represented by `DropdownNavigationItem` instances, which extend the `NavigationItem` class and contain an array of additional `NavigationItem` instances.
 
 ```php
-use Hyde\Framework\Features\Navigation\NavItem;
-use Hyde\Framework\Features\Navigation\DropdownNavItem;
+use Hyde\Framework\Features\Navigation\NavigationItem;
+use Hyde\Framework\Features\Navigation\DropdownNavigationItem;
 ```
 
 ## The Navigation API

packages/framework/config/hyde.php

@@ -350,7 +350,7 @@
         // To get started quickly, you can uncomment the defaults here.
         // See the documentation link above for more information.
         'custom' => [
-            // NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+            // NavigationItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
         ],
 
         // How should pages in subdirectories be displayed in the menu?

packages/framework/resources/views/components/docs/sidebar-items.blade.php

@@ -6,7 +6,7 @@
     </ul>
 @else
     <ul id="sidebar-items" role="list">
-        @php /** @var \Hyde\Framework\Features\Navigation\NavGroupItem $group */ @endphp
+        @php /** @var \Hyde\Framework\Features\Navigation\NavigationGroupItem $group */ @endphp
         @foreach ($sidebar->getItems() as $group)
             <li class="sidebar-group" role="listitem" @if($sidebar->isCollapsible()) x-data="{ groupOpen: {{ $sidebar->isGroupActive($group->getGroupKey()) ? 'true' : 'false' }} }" @endif>
                 <header @class(['sidebar-group-header p-2 px-4 -ml-2 flex justify-between items-center', 'group hover:bg-black/10' => $sidebar->isCollapsible()]) @if($sidebar->isCollapsible()) @click="groupOpen = ! groupOpen" @endif>

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

@@ -17,13 +17,15 @@
             <svg x-show="! navigationOpen" title="Open Navigation Menu" class="dark:fill-gray-200"
                  style="display: block;"
                  id="open-main-navigation-menu-icon" xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24"
-                 width="24"><title>Open Menu</title>
+                 width="24">
+                <title>Open Menu</title>
                 <path d="M0 0h24v24H0z" fill="none"/>
                 <path d="M3 18h18v-2H3v2zm0-5h18v-2H3v2zm0-7v2h18V6H3z"/>
             </svg>
             <svg x-show="navigationOpen" title="Close Navigation Menu" class="dark:fill-gray-200" style="display: none;"
                  id="close-main-navigation-menu-icon" xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24"
-                 width="24"><title>Close Menu</title>
+                 width="24">
+                <title>Close Menu</title>
                 <path d="M0 0h24v24H0z" fill="none"></path>
                 <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path>
             </svg>
@@ -35,7 +37,7 @@
         <ul aria-label="Navigation links" class="md:flex-grow md:flex justify-end">
             @foreach ($navigation->getItems() as $item)
                 <li class="md:mx-2">
-                    @if($item instanceof \Hyde\Framework\Features\Navigation\NavGroupItem)
+                    @if($item instanceof \Hyde\Framework\Features\Navigation\NavigationGroupItem)
                         <x-hyde::navigation.dropdown :label="$item->getLabel()" :items="$item->getItems()"/>
                     @else
                         <x-hyde::navigation.navigation-link :item="$item"/>

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

@@ -56,7 +56,7 @@ public function isCollapsible(): bool
 
     public function hasGroups(): bool
     {
-        return $this->getItems()->contains(fn (NavItem $item): bool => $item instanceof NavGroupItem);
+        return $this->getItems()->contains(fn (NavigationItem $item): bool => $item instanceof NavigationGroupItem);
     }
 
     /**
@@ -66,11 +66,11 @@ public function hasGroups(): bool
      *
      * For index pages, this will also return true for the first group in the menu, unless the index page has a specific group set.
      *
-     * We have this logic here because not all NavItem instances belong to sidebars, and we need data from both.
+     * We have this logic here because not all NavigationItem instances belong to sidebars, and we need data from both.
      */
     public function isGroupActive(string $group): bool
     {
-        $groupMatchesCurrentPageGroup = NavItem::normalizeGroupKey(Render::getPage()->navigationMenuGroup()) === $group;
+        $groupMatchesCurrentPageGroup = NavigationItem::normalizeGroupKey(Render::getPage()->navigationMenuGroup()) === $group;
 
         if ($this->isCurrentPageIndexPage()) {
             return $this->shouldIndexPageBeActive($group) || $groupMatchesCurrentPageGroup;

packages/framework/src/Framework/Features/Navigation/NavGroupItem.php → packages/framework/src/Framework/Features/Navigation/NavigationGroupItem.php

@@ -15,9 +15,9 @@
  *
  * @todo Consider extracting trait for shared code with navigation menu class
  */
-class NavGroupItem extends NavItem
+class NavigationGroupItem extends NavigationItem
 {
-    /** @var array<\Hyde\Framework\Features\Navigation\NavItem> */
+    /** @var array<\Hyde\Framework\Features\Navigation\NavigationItem> */
     protected array $items = [];
 
     public function __construct(string $label, array $items = [], int $priority = NavigationMenu::LAST)
@@ -32,7 +32,7 @@ public function __construct(string $label, array $items = [], int $priority = Na
      *
      * For the main navigation menu, this stores any dropdown items.
      *
-     * @return array<\Hyde\Framework\Features\Navigation\NavItem>
+     * @return array<\Hyde\Framework\Features\Navigation\NavigationItem>
      */
     public function getItems(): array
     {
@@ -42,7 +42,7 @@ public function getItems(): array
     /**
      * Add a navigation item to the grouped navigation item.
      */
-    public function addItem(NavItem $item): static
+    public function addItem(NavigationItem $item): static
     {
         $item->group ??= $this->group;
 
@@ -54,7 +54,7 @@ public function addItem(NavItem $item): static
     /**
      * Add multiple navigation items to the grouped navigation item.
      *
-     * @param  array<\Hyde\Framework\Features\Navigation\NavItem>  $items
+     * @param  array<\Hyde\Framework\Features\Navigation\NavigationItem>  $items
      */
     public function addItems(array $items): static
     {
@@ -73,7 +73,7 @@ public function addItems(array $items): static
     public function getPriority(): int
     {
         if ($this->containsOnlyDocumentationPages()) {
-            return min($this->priority, collect($this->getItems())->min(fn (NavItem $child): int => $child->getPriority()));
+            return min($this->priority, collect($this->getItems())->min(fn (NavigationItem $child): int => $child->getPriority()));
         }
 
         return parent::getPriority();
@@ -85,7 +85,7 @@ protected function containsOnlyDocumentationPages(): bool
             return false;
         }
 
-        return collect($this->getItems())->every(function (NavItem $child): bool {
+        return collect($this->getItems())->every(function (NavigationItem $child): bool {
             return (! $child->getRoute() instanceof ExternalRoute) && $child->getRoute()->getPage() instanceof DocumentationPage;
         });
     }

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

@@ -18,10 +18,10 @@
  *
  * You have a few options to construct a navigation menu item:
  *   1. You can supply a Route directly and explicit properties to the constructor
- *   2. You can use NavItem::fromRoute() to use data from the route
- *   3. You can use NavItem::forLink() for an external or un-routed link
+ *   2. You can use NavigationItem::fromRoute() to use data from the route
+ *   3. You can use NavigationItem::forLink() for an external or un-routed link
  */
-class NavItem implements Stringable
+class NavigationItem implements Stringable
 {
     protected ?Route $route;
     protected string $label;
@@ -83,12 +83,12 @@ public static function forLink(string $href, string $label, int $priority = Navi
      * Create a new dropdown navigation menu item.
      *
      * @param  string  $label  The label of the dropdown item.
-     * @param  array<NavItem>  $items  The items to be included in the dropdown.
+     * @param  array<NavigationItem>  $items  The items to be included in the dropdown.
      * @param  int  $priority  The priority of the dropdown item. Leave blank to use the default priority, which is last in the menu.
      */
-    public static function forGroup(string $label, array $items, int $priority = NavigationMenu::LAST): NavGroupItem
+    public static function forGroup(string $label, array $items, int $priority = NavigationMenu::LAST): NavigationGroupItem
     {
-        return new NavGroupItem($label, $items, $priority);
+        return new NavigationGroupItem($label, $items, $priority);
     }
 
     /**
@@ -145,7 +145,7 @@ public function getGroupKey(): ?string
     }
 
     /**
-     * Check if the NavItem instance is the current page being rendered.
+     * Check if the NavigationItem instance is the current page being rendered.
      */
     public function isActive(): bool
     {

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

@@ -20,7 +20,7 @@ abstract class NavigationMenu
     public const DEFAULT = 500;
     public const LAST = 999;
 
-    /** @var \Illuminate\Support\Collection<\Hyde\Framework\Features\Navigation\NavItem> */
+    /** @var \Illuminate\Support\Collection<\Hyde\Framework\Features\Navigation\NavigationItem> */
     protected Collection $items;
 
     public function __construct(Arrayable|array $items = [])
@@ -41,21 +41,21 @@ public function __construct(Arrayable|array $items = [])
      *
      * Items are automatically sorted by their priority, falling back to the order they were added.
      *
-     * @return \Illuminate\Support\Collection<\Hyde\Framework\Features\Navigation\NavItem>
+     * @return \Illuminate\Support\Collection<\Hyde\Framework\Features\Navigation\NavigationItem>
      */
     public function getItems(): Collection
     {
         // The reason we sort them here is that navigation items can be added from different sources,
         // so any sorting we do in generator actions will only be partial. This way, we can ensure
         // that the items are always freshly sorted by their priorities when they are retrieved.
 
-        return $this->items->sortBy(fn (NavItem $item) => $item->getPriority())->values();
+        return $this->items->sortBy(fn (NavigationItem $item) => $item->getPriority())->values();
     }
 
     /**
      * Add a navigation item to the navigation menu.
      */
-    public function add(NavItem $item): void
+    public function add(NavigationItem $item): void
     {
         $this->items->push($item);
     }

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

@@ -24,7 +24,7 @@
  */
 class NavigationMenuGenerator
 {
-    /** @var \Illuminate\Support\Collection<string, \Hyde\Framework\Features\Navigation\NavItem> */
+    /** @var \Illuminate\Support\Collection<string, \Hyde\Framework\Features\Navigation\NavigationItem> */
     protected Collection $items;
 
     /** @var \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route> */
@@ -71,18 +71,18 @@ protected function generate(): void
                 if ($this->canGroupRoute($route)) {
                     $this->addRouteToGroup($route);
                 } else {
-                    $this->items->put($route->getRouteKey(), NavItem::forRoute($route));
+                    $this->items->put($route->getRouteKey(), NavigationItem::forRoute($route));
                 }
             }
         });
 
         if ($this->generatesSidebar) {
             // If there are no pages other than the index page, we add it to the sidebar so that it's not empty
             if ($this->items->count() === 0 && DocumentationPage::home() !== null) {
-                $this->items->push(NavItem::forRoute(DocumentationPage::home()));
+                $this->items->push(NavigationItem::forRoute(DocumentationPage::home()));
             }
         } else {
-            collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavItem $item): void {
+            collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem $item): void {
                 // Since these were added explicitly by the user, we can assume they should always be shown
                 $this->items->push($item);
             });
@@ -133,7 +133,7 @@ protected function canGroupRoute(Route $route): bool
 
     protected function addRouteToGroup(Route $route): void
     {
-        $item = NavItem::forRoute($route);
+        $item = NavigationItem::forRoute($route);
 
         $groupName = $this->generatesSidebar ? ($item->getGroupKey() ?? 'Other') : $item->getGroupKey();
 
@@ -146,22 +146,22 @@ protected function addRouteToGroup(Route $route): void
         }
     }
 
-    protected function getOrCreateGroupItem(string $groupName): NavGroupItem
+    protected function getOrCreateGroupItem(string $groupName): NavigationGroupItem
     {
         $groupKey = Str::slug($groupName);
         $group = $this->items->get($groupKey);
 
-        if ($group instanceof NavGroupItem) {
+        if ($group instanceof NavigationGroupItem) {
             return $group;
-        } elseif ($group instanceof NavItem) {
+        } elseif ($group instanceof NavigationItem) {
             // We are trying to add children to an existing navigation menu item,
             // so here we create a new instance to replace the base one, this
             // does mean we lose the destination as we can't link to them.
 
             // Todo: Add note in documentation about this behavior
             // Example file structure: _pages/foo.md, _pages/foo/bar.md, _pages/foo/baz.md, here the link to foo will be lost.
 
-            $item = new NavGroupItem($group->getLabel(), [], $group->getPriority());
+            $item = new NavigationGroupItem($group->getLabel(), [], $group->getPriority());
 
             $this->items->put($groupKey, $item);
 
@@ -171,13 +171,13 @@ protected function getOrCreateGroupItem(string $groupName): NavGroupItem
         return $this->createGroupItem($groupKey, $groupName);
     }
 
-    protected function createGroupItem(string $groupKey, string $groupName): NavGroupItem
+    protected function createGroupItem(string $groupKey, string $groupName): NavigationGroupItem
     {
         $label = $this->searchForGroupLabelInConfig($groupKey) ?? $groupName;
 
         $priority = $this->searchForGroupPriorityInConfig($groupKey);
 
-        return NavItem::forGroup($this->normalizeGroupLabel($label), [], $priority ?? NavigationMenu::LAST);
+        return NavigationItem::forGroup($this->normalizeGroupLabel($label), [], $priority ?? NavigationMenu::LAST);
     }
 
     protected function normalizeGroupLabel(string $label): string