Refactor documentation sidebar internals

resources/views/layouts/docs.blade.php

@@ -40,24 +40,22 @@
 					@endif
 				</strong>
 				@include('hyde::components.navigation.theme-toggle-button')
-
 			</div>
 		</header>
 		<nav id="sidebar-navigation">
 			<ul id="sidebar-navigation-menu" role="list">
-				@foreach (Hyde\Framework\Actions\GeneratesDocumentationSidebar::get($currentPage) as $item)
-				<li @class([ 'sidebar-navigation-item' , 'active'=> $item['active']
-					])>
-					@if($item['active'])
-					<a href="{{ $item['slug'] }}.html" aria-current="true">{{
-						$item['title'] }}</a>
+				@foreach (Hyde\Framework\Services\DocumentationSidebarService::get() as $item)
+				<li @class([ 'sidebar-navigation-item' , 'active'=> $item->destination === $docs->slug])>
+					@if($item->destination === $docs->slug)
+					<a href="{{ $item->destination }}.html" aria-current="true">{{
+						$item->label }}</a>
 
 					@if(isset($docs->tableOfContents))
 					<span class="sr-only">Table of contents</span>
 					{!! ($docs->tableOfContents) !!}
 					@endif
 					@else
-					<a href="{{ $item['slug'] }}.html">{{ $item['title'] }}</a>
+					<a href="{{ $item->destination }}.html">{{ $item->label }}</a>
 					@endif
 				</li>
 				@endforeach

src/Actions/GeneratesDocumentationSidebar.php

@@ -9,6 +9,8 @@
 
 /**
  * Create the sidebar items for the documentation page.
+ *
+ * @deprecated use the DocumentationSidebarService instead
  */
 class GeneratesDocumentationSidebar
 {

src/Contracts/DocumentationSidebarContract.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Hyde\Framework\Contracts;
+
+use Hyde\Framework\Models\DocumentationSidebarItem;
+
+interface DocumentationSidebarContract
+{
+    /**
+     * Add a DocumentationSidebarItem to the sidebar collection.
+     */
+    public function addItem(DocumentationSidebarItem $item): self;
+
+    /**
+     * Sort the items in the collection by their priority.
+     */
+    public function sortItems(): self;
+
+    /**
+     * Get the collection instance.
+     */
+    public function getCollection(): self;
+}

src/Contracts/DocumentationSidebarServiceContract.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Hyde\Framework\Contracts;
+
+use Hyde\Framework\Models\DocumentationSidebar;
+
+interface DocumentationSidebarServiceContract
+{
+    /**
+     * Generate and return a new DocumentationSidebar collection.
+     */
+    public static function get(): DocumentationSidebar;
+
+    /**
+     * Parse the _docs directory for sidebar items to create a new collection.
+     */
+    public function createSidebar(): self;
+
+    /**
+     * Get the collection of sidebar items in the class.
+     */
+    public function getSidebar(): DocumentationSidebar;
+}

src/Models/DocumentationSidebar.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Hyde\Framework\Models;
+
+use Hyde\Framework\Contracts\DocumentationSidebarContract;
+use Illuminate\Support\Collection;
+
+/**
+ * The documentation sidebar, containing all the sidebar items.
+ *
+ * Extends the \Illuminate\Support\Collection class and has helper
+ * methods to fluently add DocumentationSidebarItems to the
+ * collection using method chaining.
+ *
+ * @see \Tests\Feature\Services\DocumentationSidebarServiceTest
+ */
+class DocumentationSidebar extends Collection implements DocumentationSidebarContract
+{
+    public function addItem(DocumentationSidebarItem $item): self
+    {
+        $this->push($item);
+
+        return $this;
+    }
+
+    public function sortItems(): self
+    {
+        return $this->sortBy('priority')
+            ->values(); // Reset the keys to consecutively numbered indexes:
+    }
+
+    public function getCollection(): self
+    {
+        return $this;
+    }
+}

src/Models/DocumentationSidebarItem.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Hyde\Framework\Models;
+
+use Hyde\Framework\Hyde;
+use Spatie\YamlFrontMatter\YamlFrontMatter;
+
+/**
+ * Object containing information for a sidebar item.
+ *
+ * @see \Tests\Feature\Services\DocumentationSidebarServiceTest
+ */
+class DocumentationSidebarItem
+{
+    public string $label;
+    public string $destination;
+    public int $priority;
+
+    public function __construct(string $label, string $destination, ?int $priority = null)
+    {
+        $this->label = $label;
+        $this->destination = $destination;
+        $this->priority = $priority ?? $this->findPriorityInConfig($destination);
+    }
+
+    protected function findPriorityInConfig(string $slug): int
+    {
+        $orderIndexArray = config('hyde.documentationPageOrder', []);
+
+        if (! in_array($slug, $orderIndexArray)) {
+            return 500;
+        }
+
+        return array_search($slug, $orderIndexArray); //  + 250?
+    }
+
+    public static function parseFromFile(string $documentationPageSlug): static
+    {
+        $matter = YamlFrontMatter::markdownCompatibleParse(
+            file_get_contents(Hyde::path('_docs/'.$documentationPageSlug.'.md'))
+        )->matter();
+
+        return new static(
+            $matter['label'] ?? Hyde::titleFromSlug($documentationPageSlug),
+            $documentationPageSlug,
+            $matter['priority'] ?? null
+        );
+    }
+}

src/Services/DocumentationSidebarService.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Hyde\Framework\Services;
+
+use Hyde\Framework\Contracts\DocumentationSidebarServiceContract;
+use Hyde\Framework\Models\DocumentationSidebar;
+use Hyde\Framework\Models\DocumentationSidebarItem;
+
+/**
+ * Service class to create and manage the sidebar collection object.
+ *
+ * @see \Tests\Feature\Services\DocumentationSidebarServiceTest
+ */
+class DocumentationSidebarService implements DocumentationSidebarServiceContract
+{
+    /**
+     * The sidebar object created and managed by the service instance.
+     */
+    protected DocumentationSidebar $sidebar;
+
+    /**
+     * Shorthand to create a new Sidebar object using default methods.
+     */
+    public static function get(): DocumentationSidebar
+    {
+        return ((new static)->createSidebar()->withoutIndex()->getSidebar()
+        )->sortItems()->getCollection();
+    }
+
+    /**
+     * Parse the _docs directory for sidebar items to create a new collection.
+     */
+    public function createSidebar(): self
+    {
+        $this->sidebar = new DocumentationSidebar();
+
+        foreach ($this->getSidebarItems() as $slug) {
+            $this->sidebar->addItem(
+                $this->createSidebarItemFromSlug($slug)
+            );
+        }
+
+        return $this;
+    }
+
+    /**
+     * Get the sidebar object created and managed by the service instance.
+     */
+    public function getSidebar(): DocumentationSidebar
+    {
+        return $this->sidebar;
+    }
+
+    /**
+     * Remove the index page from the sidebar collection.
+     */
+    protected function withoutIndex(): self
+    {
+        $this->sidebar = $this->sidebar->reject(function (DocumentationSidebarItem $item) {
+            return $item->destination === 'index';
+        });
+
+        return $this;
+    }
+
+    /**
+     * Get an array of source files to add to the sidebar.
+     */
+    protected function getSidebarItems(): array
+    {
+        return CollectionService::getDocumentationPageList();
+    }
+
+    /**
+     * Generate a SidebarItem object from a source file referenced by its slug.
+     */
+    protected function createSidebarItemFromSlug(string $slug): DocumentationSidebarItem
+    {
+        return DocumentationSidebarItem::parseFromFile($slug);
+    }
+}

tests/Feature/GeneratesDocumentationSidebarTest.php

@@ -8,6 +8,8 @@
 
 /**
  * @covers \Hyde\Framework\Actions\GeneratesDocumentationSidebar
+ *
+ * @deprecated use the DocumentationSidebarServiceTest instead
  */
 class GeneratesDocumentationSidebarTest extends TestCase
 {