Create new documentation for simplified API

Author: emmadesilva

docs/advanced-features/navigation-api.md

@@ -155,120 +155,45 @@ The `NavigationMenu` class represents a navigation menu. It contains a collectio
 
 ## NavigationItem
 
-The `NavigationItem` class represents a single item in a navigation menu. It contains information such as the destination link or route, a label, and priority for ordering in the menu.
-
-Here is the constructor signature and a quick reference of the methods available on the `NavigationItem` class, and their types. Keep on reading to see more detailed examples and explanations.
-
-```php
-use Hyde\Framework\Features\Navigation\NavigationItem;
-
-$item = new NavigationItem(Route|string $destination, string $label, int $priority = 500);
-
-$item->getLink():  string; // Returns the resolved link route or destination URL.
-$item->getLabel(): string; // Returns the label of the item.
-$item->isActive(): bool;   // Returns true if the item is the page being rendered.
-$item->getPriority(): int; // Returns the priority of the item.
-$item->getPage(): ?HydePage; // Returns the underlying Page instance, if there is one.
-```
+The `NavigationItem` class is an abstraction for a navigation menu item containing useful information like the destination, label, and priority.
 
 ### Creating Navigation Items
 
-There are several ways to create navigation items using the `NavigationItem` class.
-
-#### Direct instantiation
-
-You can create instances directly by passing either a URL or a Route instance to the constructor. 
-
-The first parameter is the destination, the second is the label, and the third optional parameter is the priority.
-
-```php
-$item = new NavigationItem('index', 'Home');
-$item = new NavigationItem(Routes::get('index'), 'Home');
-$item = new NavigationItem('https://example.com', 'External Link');
-```
-
-#### Setting Priority
+There are two syntaxes for creating NavigationItem instances, you can use a standard constructor or the static create method.
+Both options provide the exact same signature and functionality, so it's just a matter of preference which one you use.
 
-You can set the priority of the item, which determines its position in the menu.
+The constructors take three parameters: the destination, the label, and the optional priority.
+The destination can be a `Route` instance, a route key string, or an external URL.
 
 ```php
-$item = new NavigationItem(Routes::get('index'), 'Home', 25);
-```
-
-#### Static Creation Method
-
-You can use the static `create` method, which can automatically fill in the label and priority from a Route.
-
-```php
-$item = NavigationItem::create(Routes::get('index'));
-```
-
-You can also pass a custom label and priority to the `create` method to override the defaults.
-
-```php
-$item = NavigationItem::create(Routes::get('index'), 'Custom Label', 50);
-```
-
-#### Using Route Keys and URLs
-
-The `create` method works with route keys and URLs.
-
-```php
-$item = NavigationItem::create('index');
-$item = NavigationItem::create('https://example.com');
-```
-
-Unless you pass a custom label to URL items, the label will be the URL itself.
-
-```php
-$item = NavigationItem::create('https://example.com');
-```
-
-### Navigation Item Methods
-
-### Getting Label and Link
-
-```php
-$item = NavigationItem::create('index');
-
-// Get the label of the item.
-$item->getLabel(); // Returns 'Home'
-
-// Get the link of the item.
-$item->getLink(); // Returns 'index.html'
-```
-
-You can also get the link by casting the item to a string.
+use Hyde\Framework\Features\Navigation\NavigationItem;
 
-```php
-(string) $item; // Returns 'index.html'
+$item = new NavigationItem($destination, $label, $priority);
+$item = NavigationItem::create($destination, $label, $priority);
 ```
 
-### Getting Priority
-
-```php
-$item->getPriority(); // Returns 0
-```
+#### Using Routes
 
-### Getting Page Instance
+Using the HydePHP routing system is the recommended way to create navigation items leading to pages within your project,
+as they will automatically have links resolved to the correct URL, and Hyde can check if the items are active.
+Additionally, Hyde will use the page data as the label and priority defaults unless you override them.
 
-You can get the underlying Page instance of the item, if it exists.
+Create routed navigation items by providing either a `Route` instance or a route key string as the destination.
 
 ```php
-$item->getPage(); // Returns instance of BladePage or null
-```
-
-### Checking Active State
+// Using a Route instance will automatically fill in the label and priority from the route's connected page.
+$item = new NavigationItem(Routes::get('index'));
+// ['destination' => 'index.html', 'label' => 'Home', 'priority' => 0]
 
-You can check if the item is active (i.e., the current page being rendered).
+// Using a route key provides the same functionality as using a Route instance.
+// Make sure the route exists otherwise it will be treated as a link.
+$item = new NavigationItem('index'); // Exactly the same as above, but without type safety.
 
-```php
-$item->isActive(); // Returns false
+// Setting the label and/or priorities will override the page's data.
+$item = new NavigationItem(Routes::get('index'), 'Custom Label', 10);
+// ['destination' => 'index.html', 'label' => 'Custom Label', 'priority' => 10]
 ```
 
-This concludes the documentation for the `NavigationItem` class.
-
-
 ## NavigationGroup
 
 The `NavigationGroup` class represents a group of items in a navigation menu. It contains a label, priority, and a collection of navigation items.

packages/framework/tests/Feature/NavigationAPITest.php

@@ -51,44 +51,37 @@ public function testServiceContainerMenus()
 
     public function testNavigationItems()
     {
-        // Each navigation item is represented by a NavigationItem instance containing the needed information.
+        // The NavigationItem class is an abstraction for a navigation menu item containing useful information like the destination, label, and priority.
 
         // ## Creating Navigation Items
 
-        // There are a few ways to create navigation items, depending on your needs.
+        // There are two syntaxes for creating NavigationItem instances, you can use a standard constructor or the static create method.
+        // Both options provide the exact same signature and functionality, so it's just a matter of preference which one you use.
 
-        // You can create instances directly by passing either a URL or Route instance to the constructor.
-        $item = new NavigationItem(Routes::get('index'), 'Home');
-        $this->assertInstanceOf(NavigationItem::class, $item);
-        $item = new NavigationItem('https://example.com', 'External Link');
-        $this->assertInstanceOf(NavigationItem::class, $item);
+        // The constructors take three parameters: the destination, the label, and the optional priority.
+        // The destination can be a Route instance, a route key string, or an external URL.
 
-        // You can also set the priority of the item, which determines its position in the menu.
-        $item = new NavigationItem(Routes::get('index'), 'Home', 25);
-        $this->assertSame(25, $item->getPriority());
+        // Using a Route instance will automatically fill in the label and priority from the route's connected page.
+        $item = new NavigationItem(Routes::get('index'));
+        $this->assertData(['destination' => 'index.html', 'label' => 'Home', 'priority' => 0], $item);
 
-        // You can also create instances using the static create method, which can automatically fill in the label and priority from a Route.
-        $item = NavigationItem::create(Routes::get('index'));
-        $this->assertSame('Home', $item->getLabel());
-        $this->assertSame(0, $item->getPriority());
+        // Using a route key provides the same functionality as using a Route instance.
+        // Make sure the route exists otherwise it will be treated as a link.
+        $item = new NavigationItem('index');
+        $this->assertEquals(new NavigationItem(Routes::get('index')), $item);
 
-        // You can also pass a custom label and priority to the create method to override the defaults.
-        $item = NavigationItem::create(Routes::get('index'), 'Custom Label', 50);
-        $this->assertSame('Custom Label', $item->getLabel());
-        $this->assertSame(50, $item->getPriority());
-
-        // The create method also works with route keys.
-        $item = NavigationItem::create('index');
-        $this->assertSame('Home', $item->getLabel());
-        $this->assertEquals(NavigationItem::create('index'), NavigationItem::create(Routes::get('index')));
+        // Setting the label and/or priorities will override the page's data.
+        $item = new NavigationItem(Routes::get('index'), 'Custom Label', 10);
+        $this->assertData(['destination' => 'index.html', 'label' => 'Custom Label', 'priority' => 10], $item);
 
-        // You can also pass a URL to the create method.
-        $item = NavigationItem::create('https://example.com');
-        $this->assertSame('https://example.com', $item->getLink());
+        // You can also pass an external URL as the destination.
+        $item = new NavigationItem('https://example.com', 'External Link', 10);
+        $this->assertData(['destination' => 'https://example.com', 'label' => 'External Link', 'priority' => 10], $item);
 
-        // Unless you pass a custom label to URL items, the label will be the URL itself.
-        $item = NavigationItem::create('https://example.com');
-        $this->assertSame('https://example.com', $item->getLabel());
+        // If you do not set a label for links, the label will default to the URL.
+        // And if uf you do not set a priority, it will default to 500.
+        $item = new NavigationItem('https://example.com');
+        $this->assertData(['destination' => 'https://example.com', 'label' => 'https://example.com', 'priority' => 500], $item);
 
         // ## Navigation Item Methods
 
@@ -229,4 +222,15 @@ protected function removeIndentation(string $actual): string
     {
         return implode("\n", array_map('trim', explode("\n", $actual)));
     }
+
+    protected function assertData(array $expected, NavigationItem $item): void
+    {
+        $actual = [
+            'destination' => $item->getLink(),
+            'label' => $item->getLabel(),
+            'priority' => $item->getPriority(),
+        ];
+
+        $this->assertSame($expected, $actual);
+    }
 }