Merge pull request #498 from hydephp/breaking-refactor-of-navigation-…

…groups

Breaking refactor to further unify sidebar and navigation API

RELEASE_NOTES.md

@@ -18,6 +18,7 @@ The most high impact change is change of sidebar front matter options, and relat
 ### Added
 - Added a JSON build information manifest automatically generated after a site build [#465](https://github.com/hydephp/develop/pull/465)
 - Added support for "dot notation" to the `HydePage::get()` method [#497](https://github.com/hydephp/develop/pull/497)
+- Added a NavigationData object to HydePage.php
 
 ### Changed
 
@@ -51,7 +52,9 @@ This change also bubbles to the HydePage accessors, though that will only affect
 - The `StaticPageBuilder::$outputPath` property is now a relative path instead of absolute
 - Refactored how navigation and sidebar data are handled, unifying the API, see below for more details
 - The algorithm for finding the navigation and sidebar orders has been updated, this may affect the order of your pages, and may require you to re-tweak any custom priorities.
+- The navigation link to documentation index page now has default priority 500 instead of 100
 - internal: Move responsibility for filtering documentation pages to the navigation menus (this means that documentation pages that are not 'index' are no longer regarded as hidden)
+- internal: The HydePage::$navigation property is now a NavigationData object instead of an array, however the object extends ArrayObject, so it should be mostly compatible with existing code
 
 #### Class and method renames
 - Renamed base class AbstractPage to HydePage
@@ -74,7 +77,7 @@ This change also bubbles to the HydePage accessors, though that will only affect
 - Moved class FindsContentLengthForImageObject into Constructors namespace
 
 #### Page-model specific
-- Removed action class FindsNavigationDataForPage.php (merged into HydePage.php via the HasNavigationData trait)
+- Removed action class FindsNavigationDataForPage.php (merged into HydePage.php via the GeneratesNavigationData trait)
 - Renamed method outputLocation to outputPath in HydePage.php
 - Renamed method qualifyBasename to sourcePath in HydePage.php
 - Renamed method getOutputLocation to outputLocation in HydePage.php
@@ -86,16 +89,16 @@ This change also bubbles to the HydePage accessors, though that will only affect
 
 #### Documentation page front matter changes
 
-- Deprecated property `$category` in `DocumentationPage.php`
 - Removed property `$label` in `DocumentationPage.php` (use `$navigation['title']` instead)
 - Removed property `$hidden` in `DocumentationPage.php` (use `$navigation['hidden']` instead)
 - Removed property `$priority` in `DocumentationPage.php` (use `$navigation['priority']` instead)
+- Removed property `$category` in `DocumentationPage.php` (use `$navigation['group']` instead)
 - Removed front matter option`label` (use `navigation.label` instead)
 - Removed front matter option`hidden` (use `navigation.hidden` instead)
 - Removed front matter option`priority` (use `navigation.priority` instead)
+- Removed front matter option`category` (use `navigation.group` instead)
 - To access the sidebar label setting via class property, use `$navigation['label']` instead of `$label`, etc.
 - To access the sidebar label setting via front matter getters, use `navigation.label` instead of `label`, etc.
-- The navigation link to documentation index page now has default priority 500 instead of 100
 
 ### Deprecated
 - for soon-to-be removed features.

docs/creating-content/documentation-pages.md

@@ -145,10 +145,11 @@ Any pages without the category front matter will get put in the "Other" category
 To enable sidebar grouping, you can add the following front matter to your documentation pages:
 
 ```yaml
-category: "Getting Started"
+navigation:
+  group: "Getting Started"
 ```
 
-#### Using sub-directories
+#### Using subdirectories
 
 Since [v0.52.0-beta](https://github.com/hydephp/develop/releases/tag/v0.52.0-beta), you can also automatically group your documentation pages by placing source files in sub-directories.
 

packages/framework/src/Concerns/HydePage.php

@@ -11,6 +11,7 @@
 use Hyde\Framework\Hyde;
 use Hyde\Framework\Models\FrontMatter;
 use Hyde\Framework\Models\Metadata\Metadata;
+use Hyde\Framework\Models\NavigationData;
 use Hyde\Framework\Models\Route;
 use Hyde\Framework\Services\DiscoveryService;
 use Illuminate\Support\Arr;
@@ -33,7 +34,7 @@
 abstract class HydePage implements CompilableContract, PageSchema
 {
     use ConstructsPageSchemas;
-    use Internal\HasNavigationData;
+    use Internal\GeneratesNavigationData;
 
     public static string $sourceDirectory;
     public static string $outputDirectory;
@@ -48,7 +49,7 @@ abstract class HydePage implements CompilableContract, PageSchema
 
     public string $title;
     public ?string $canonicalUrl = null;
-    public ?array $navigation = null;
+    public ?NavigationData $navigation = null;
 
     public function __construct(string $identifier = '', FrontMatter|array $matter = [])
     {
@@ -263,4 +264,24 @@ public function renderPageMetadata(): string
     {
         return $this->metadata->render();
     }
+
+    public function showInNavigation(): bool
+    {
+        return ! $this->navigation['hidden'];
+    }
+
+    public function navigationMenuPriority(): int
+    {
+        return $this->navigation['priority'];
+    }
+
+    public function navigationMenuLabel(): string
+    {
+        return $this->navigation['label'];
+    }
+
+    public function navigationMenuGroup(): ?string
+    {
+        return $this->navigation['group'];
+    }
 }

packages/framework/src/Concerns/Internal/ConstructsPageSchemas.php

@@ -9,7 +9,6 @@
 use Hyde\Framework\Models\Author;
 use Hyde\Framework\Models\DateString;
 use Hyde\Framework\Models\Image;
-use Illuminate\Support\Str;
 
 trait ConstructsPageSchemas
 {
@@ -20,10 +19,6 @@ protected function constructPageSchemas(): void
         if ($this instanceof BlogPostSchema) {
             $this->constructBlogPostSchema();
         }
-
-        if ($this instanceof DocumentationPageSchema) {
-            $this->constructDocumentationPageSchema();
-        }
     }
 
     protected function constructPageSchema(): void
@@ -86,20 +81,4 @@ protected function getImage(): ?Image
 
         return null;
     }
-
-    protected function constructDocumentationPageSchema(): void
-    {
-        $this->category = $this->getDocumentationPageCategory();
-    }
-
-    protected function getDocumentationPageCategory(): ?string
-    {
-        // If the documentation page is in a subdirectory,
-        // then we can use that as the category name.
-        // Otherwise, we look in the front matter.
-
-        return str_contains($this->identifier, '/')
-            ? Str::before($this->identifier, '/')
-            : $this->matter('category', 'other');
-    }
 }

packages/framework/src/Concerns/Internal/HasNavigationData.php → packages/framework/src/Concerns/Internal/GeneratesNavigationData.php

@@ -2,29 +2,18 @@
 
 namespace Hyde\Framework\Concerns\Internal;
 
+use Hyde\Framework\Models\NavigationData;
 use Hyde\Framework\Models\Pages\DocumentationPage;
 use Hyde\Framework\Models\Pages\MarkdownPost;
+use Illuminate\Support\Str;
 
 /**
  * @internal Trait for HydePages to manage data used for navigation menus and the documentation sidebar.
+ *
+ * @see \Hyde\Framework\Concerns\HydePage
  */
-trait HasNavigationData
+trait GeneratesNavigationData
 {
-    public function showInNavigation(): bool
-    {
-        return ! $this->navigation['hidden'];
-    }
-
-    public function navigationMenuPriority(): int
-    {
-        return $this->navigation['priority'];
-    }
-
-    public function navigationMenuLabel(): string
-    {
-        return $this->navigation['label'];
-    }
-
     protected function constructNavigationData(): void
     {
         $this->setNavigationData(
@@ -39,17 +28,19 @@ protected function constructSidebarNavigationData(): void
         $this->setNavigationData(
             $this->findNavigationMenuLabel(),
             $this->findNavigationMenuHidden(),
-            $this->matter('navigation.priority', $this->findNavigationMenuPriority())
+            $this->matter('navigation.priority', $this->findNavigationMenuPriority()),
+            $this->getDocumentationPageGroup()
         );
     }
 
-    protected function setNavigationData(string $label, bool $hidden, int $priority): void
+    protected function setNavigationData(string $label, bool $hidden, int $priority, ?string $group = null): void
     {
-        $this->navigation = [
+        $this->navigation = NavigationData::make([
             'label' => $label,
+            'group' => $group,
             'hidden' => $hidden,
             'priority' => $priority,
-        ];
+        ]);
     }
 
     private function findNavigationMenuLabel(): string
@@ -115,4 +106,15 @@ private function getNavigationLabelConfig(): array
             'docs/index' => 'Docs',
         ], config('hyde.navigation.labels', []));
     }
+
+    private function getDocumentationPageGroup(): ?string
+    {
+        // If the documentation page is in a subdirectory,
+        // then we can use that as the category name.
+        // Otherwise, we look in the front matter.
+
+        return str_contains($this->identifier, '/')
+            ? Str::before($this->identifier, '/')
+            : $this->matter('navigation.group', 'other');
+    }
 }

packages/framework/src/Contracts/FrontMatter/BlogPostSchema.php

@@ -3,8 +3,6 @@
 namespace Hyde\Framework\Contracts\FrontMatter;
 
 /**
- * The front matter properties supported by the following HydePHP page types and their children.
- *
  * @see \Hyde\Framework\Models\Pages\MarkdownPost
  */
 interface BlogPostSchema

packages/framework/src/Contracts/FrontMatter/DocumentationPageSchema.php

@@ -3,8 +3,6 @@
 namespace Hyde\Framework\Contracts\FrontMatter;
 
 /**
- * The front matter properties supported by the following HydePHP page types and their children.
- *
  * @see \Hyde\Framework\Models\Pages\DocumentationPage
  */
 interface DocumentationPageSchema

packages/framework/src/Contracts/FrontMatter/PageSchema.php

@@ -3,21 +3,13 @@
 namespace Hyde\Framework\Contracts\FrontMatter;
 
 /**
- * The front matter properties supported by the following HydePHP page types and their children.
- *
  * @see \Hyde\Framework\Concerns\HydePage
  */
-interface PageSchema
+interface PageSchema extends Support\NavigationSchema
 {
     public const PAGE_SCHEMA = [
         'title'         => 'string',
         'canonicalUrl'  => 'string|url',
         'navigation'    => 'array|navigation',
     ];
-
-    public const NAVIGATION_SCHEMA = [
-        'label'     => 'string',
-        'hidden'    => 'bool',
-        'priority'  => 'int',
-    ];
 }

packages/framework/src/Contracts/FrontMatter/Support/NavigationSchema.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Hyde\Framework\Contracts\FrontMatter\Support;
+
+/**
+ * @see \Hyde\Framework\Models\NavigationData
+ * @see \Hyde\Framework\Concerns\HydePage
+ */
+interface NavigationSchema
+{
+    public const NAVIGATION_SCHEMA = [
+        'label'     => 'string',
+        'group'     => 'string',
+        'hidden'    => 'bool',
+        'priority'  => 'int',
+    ];
+}

packages/framework/src/Models/Navigation/NavItem.php

@@ -121,7 +121,7 @@ public function setPriority(int $priority): static
 
     public function getGroup(): ?string
     {
-        return $this->normalizeGroupKey($this->route->getSourceModel()->get('category'));
+        return $this->normalizeGroupKey($this->route->getSourceModel()->get('navigation.group'));
     }
 
     protected function normalizeGroupKey(?string $group): ?string

packages/framework/src/Models/NavigationData.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Hyde\Framework\Models;
+
+use Hyde\Framework\Concerns\JsonSerializesArrayable;
+use Hyde\Framework\Contracts\FrontMatter\Support\NavigationSchema;
+use Illuminate\Contracts\Support\Arrayable;
+
+final class NavigationData extends \ArrayObject implements NavigationSchema, Arrayable, \JsonSerializable
+{
+    use JsonSerializesArrayable;
+
+    public ?string $label = null;
+    public ?string $group = null;
+    public ?bool $hidden = null;
+    public ?int $priority = null;
+
+    public function __construct(?string $label = null, ?string $group = null, ?bool $hidden = null, ?int $priority = null)
+    {
+        $this->label = $label;
+        $this->group = $group;
+        $this->hidden = $hidden;
+        $this->priority = $priority;
+
+        parent::__construct($this->toArray());
+    }
+
+    public static function make(array $data): self
+    {
+        return new self(
+            $data['label'] ?? null,
+            $data['group'] ?? null,
+            $data['hidden'] ?? null,
+            $data['priority'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'label' => $this->label,
+            'group' => $this->group,
+            'hidden' => $this->hidden,
+            'priority' => $this->priority,
+        ];
+    }
+}

packages/framework/src/Models/Pages/DocumentationPage.php

@@ -16,12 +16,6 @@ class DocumentationPage extends BaseMarkdownPage implements DocumentationPageSch
     public static string $outputDirectory = 'docs';
     public static string $template = 'hyde::layouts/docs';
 
-    /**
-     * @deprecated Will be replaced by navigation.group
-     * The sidebar category group, if any. Can be overridden in front matter, or by putting the source file in a subdirectory of the same category name.
-     */
-    public ?string $category = null;
-
     /** @inheritDoc */
     public function __construct(string $identifier = '', ?FrontMatter $matter = null, ?Markdown $markdown = null)
     {