Refactor documentation layout to use more components

RELEASE_NOTES.md

@@ -12,17 +12,17 @@ This update will only affect those who have written custom code that uses or typ
 - for new features.
 
 ### Changed
-- for changes in existing functionality.
+- The documentation page layout has been internally refactored to utilize more Blade components. This only affects those who have extended or customized the documentation components. Some documentation components have also been renamed.
 
 ### Deprecated
 - Deprecate interface HydeKernelContract, type hint the HydeKernel::class instead
 - Deprecate interface AssetServiceContract, type hint the AssetService::class instead
 
 ### Removed
-- for now removed features.
+- Removed legacy `.js-enabled` class from documentation pages
 
 ### Fixed
-- for any bug fixes.
+- The list element of the documentation page sidebar had a conflicting ID (`#sidebar`) and has now been changed to `#sidebar-navigation` which may break edge cases where this component is styled or interacted with outside of the framework.
 
 ### Security
 - in case of vulnerabilities.

docs/creating-content/documentation-pages.md

@@ -37,6 +37,11 @@ to keep in mind when creating blog posts so that you don't get unexpected result
 - You should always have an `index.md` file in the `_docs/` directory
 - Your page will be stored in `_site/docs/<slug>.html` unless you [change it in the config](#output-directory)
 
+### Advanced usage and customization
+
+Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content.
+Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for.
+
 
 ## Creating Documentation Pages
 You can create a Documentation page by adding a file to the `_docs` directory where the filename ends in `.md`.
@@ -311,3 +316,7 @@ Just target the `.edit-page-link` class.
 // filepath e.g. app.css
 .edit-page-link::before {content: "✏ "}
 ```
+
+#### Changing the Blade view
+
+You can also publish the `edit-source-button.blade.php` view and change it to your liking.

packages/framework/resources/views/components/docs/documentation-article.blade.php

@@ -0,0 +1,20 @@
+@props([
+    /** @var \Hyde\Framework\Services\HydeSmartDocs */
+    'document'
+])
+
+<article id="document" itemscope itemtype="http://schema.org/Article" @class(['mx-auto lg:ml-8 prose
+			dark:prose-invert max-w-3xl p-12 md:px-16 max-w-[1000px] min-h-[calc(100vh_-_4rem)]', 'torchlight-enabled'=>
+			$document->hasTorchlight()])>
+    @yield('content')
+
+    <header id="document-header" class="flex items-center flex-wrap prose-h1:mb-3">
+        {!! $document->renderHeader() !!}
+    </header>
+    <section id="document-main-content" itemprop="articleBody">
+        {!! $document->renderBody() !!}
+    </section>
+    <footer id="document-footer" class="flex items-center flex-wrap mt-8 prose-p:my-3 justify-between text-[90%]">
+        {!! $document->renderFooter() !!}
+    </footer>
+</article>

packages/framework/resources/views/components/docs/edit-source-button.blade.php

@@ -0,0 +1,5 @@
+<p class="edit-page-link">
+    <a href="{{ $href }}">
+        {{ config('docs.edit_source_link_text', 'Edit page') }}
+    </a>
+</p>

packages/framework/resources/views/components/docs/grouped-sidebar.blade.php → packages/framework/resources/views/components/docs/grouped-sidebar-navigation.blade.php

@@ -1,4 +1,4 @@
-<ul id="sidebar" role="list">
+<ul id="sidebar-navigation" role="list">
 	@foreach ($sidebar->getGroups() as $group)
 	<li class="sidebar-category mb-4 mt-4 first:mt-0" role="listitem">
 		<h4 class="sidebar-category-heading text-base font-semibold mb-2 -ml-1">{{ Hyde::makeTitle($group) }}</h4>

packages/framework/resources/views/components/docs/mobile-navigation.blade.php

@@ -0,0 +1,19 @@
+<nav id="mobile-navigation" class="bg-white dark:bg-gray-800 md:hidden flex justify-between w-full h-16 z-40 fixed left-0 top-0 p-4 leading-8 shadow-lg">
+    <strong class="px-2 mr-auto">
+        @if(DocumentationPage::home() !== null)
+            <a href="{{ DocumentationPage::home() }}">
+                {{ config('docs.header_title', 'Documentation') }}
+            </a>
+        @else
+            {{ config('docs.header_title', 'Documentation') }}
+        @endif
+    </strong>
+    <ul class="flex items-center">
+        <li class="h-8 flex mr-1">
+            <x-hyde::navigation.theme-toggle-button class="opacity-75 hover:opacity-100"/>
+        </li>
+        <li class="h-8 flex">
+            @include('hyde::components.docs.sidebar-toggle-button')
+        </li>
+    </ul>
+</nav>

packages/framework/resources/views/components/docs/search-scripts.blade.php

@@ -0,0 +1,9 @@
+<script src="https://cdn.jsdelivr.net/npm/hydesearch@0.2.1/dist/HydeSearch.min.js" defer></script>
+<script>
+    window.addEventListener('load', function () {
+        const searchIndexLocation = 'search.json';
+        const Search = new HydeSearch(searchIndexLocation);
+
+        Search.init();
+    });
+</script>

packages/framework/resources/views/components/docs/search-widget.blade.php

@@ -0,0 +1,53 @@
+<button id="searchMenuButton" x-on:click="searchWindowOpen = ! searchWindowOpen"
+        :title="searchWindowOpen ? 'Close search window' : 'Open search window'; $nextTick(() => { setTimeout(() => { document.getElementById('search-input').focus(); }); });"
+        class="absolute right-4 top-4 mr-4 z-10 opacity-75 hover:opacity-100 hidden md:block"
+        aria-label="Toggle search window">
+	<span x-show="! searchWindowOpen">
+		Search <svg class="float-left mr-1 dark:fill-white" xmlns="http://www.w3.org/2000/svg" height="24"
+                    viewBox="0 0 24 24" width="24" role="presentation">
+			<path d="M0 0h24v24H0z" fill="none"/>
+			<path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/></svg>
+	</span>
+    <span x-show="searchWindowOpen">
+		<svg class="w-6 h-6" fill="currentColor" viewBox="0 0 20 20">
+			<path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"></path>
+		</svg>
+	</span>
+</button>
+<button id="searchMenuButtonMobile" x-on:click="searchWindowOpen = ! searchWindowOpen"
+        :title="searchWindowOpen ? 'Close search window' : 'Open search window'; $nextTick(() => { setTimeout(() => { document.getElementById('search-input').focus(); }); });"
+        class="block md:hidden fixed bottom-4 right-4 z-10 rounded-full p-2 opacity-75 hover:opacity-100 fill-black bg-gray-200 dark:fill-gray-200 dark:bg-gray-700"
+        aria-label="Toggle search menu">
+    <svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24" width="24" role="presentation">
+        <path d="M0 0h24v24H0z" fill="none"/>
+        <path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/>
+    </svg>
+</button>
+
+<div id="search-window-container" x-show="searchWindowOpen" x-cloak role="dialog"
+     class="z-30 fixed top-0 left-0 w-screen h-screen flex flex-col items-center px-8 py-24 md:py-16">
+    <aside x-on:click.away="searchWindowOpen = false" id="searchMenu"
+           class="prose dark:prose-invert bg-white dark:bg-gray-800  z-50 p-4 rounded-lg overflow-y-hidden min-h-[300px] max-h-[75vh] w-[70ch] max-w-full cursor-auto ">
+        <header class="flex justify-between pb-3 mb-3 border-b dark:border-gray-700 md:hidden">
+            <strong>Search the documentation site</strong>
+            <button @click="searchWindowOpen = false" title="Close search window" class="opacity-75 hover:opacity-100"
+                    aria-label="Close search window">
+                <svg class="w-6 h-6" fill="currentColor" viewBox="0 0 20 20">
+					<path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"></path>
+                </svg>
+            </button>
+        </header>
+        <div>
+            <x-hyde::docs.search-input/>
+        </div>
+        <footer class="mt-auto -mb-2 leading-4 text-center font-mono hidden sm:flex justify-center">
+            <small>
+                Press <code><kbd title="Forward slash">/</kbd></code> to open search window.
+                Use <code><kbd title="Escape key">esc</kbd></code> to close.
+            </small>
+        </footer>
+    </aside>
+
+    <div id="search-window-backdrop" title="Click to close search window"
+         class="w-screen h-screen cursor-pointer z-40 bg-black/50 absolute top-0"></div>
+</div>

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

@@ -0,0 +1,3 @@
+<div id="sidebar-backdrop" x-show="sidebarOpen" x-transition @click="sidebarOpen = false"
+             title="Click to close sidebar" class="w-screen h-screen fixed top-0 left-0 cursor-pointer z-10 bg-black/50">
+</div>

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

@@ -0,0 +1,12 @@
+<div id="sidebar-brand" class="flex items-center justify-between h-16 py-4 px-2">
+	<strong class="px-2">
+		@if(DocumentationPage::home() !== null)
+			<a href="{{ DocumentationPage::home() }}">
+				{{ config('docs.header_title', 'Documentation') }}
+			</a>
+		@else
+			{{ config('docs.header_title', 'Documentation') }}
+		@endif
+	</strong>
+	<x-hyde::navigation.theme-toggle-button class="opacity-75 hover:opacity-100"/>
+</div>

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

@@ -0,0 +1,3 @@
+<p>
+	<a href="{{ Hyde::relativeLink('index.html') }}">Back to home page</a>
+</p>

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

@@ -0,0 +1,18 @@
+<ul id="sidebar-navigation" role="list">
+	@foreach ($sidebar->items as $item)
+	<li @class(['sidebar-navigation-item -ml-4 pl-4' , 'active bg-black/5 dark:bg-black/10'=> $item->route->getRouteKey() === $currentRoute->getRouteKey()])>
+		@if($item->route->getRouteKey() === $currentRoute->getRouteKey())
+			<a href="{{ $item->route }}" aria-current="true" class="-ml-4 p-2 block hover:bg-black/5 dark:hover:bg-black/10  text-indigo-600 dark:text-indigo-400 dark:font-medium border-l-[0.325rem] border-indigo-500 transition-colors duration-300	ease-in-out">
+				{{ $item->title }}
+			</a>
+
+			@if(config('docs.table_of_contents.enabled', true))
+				<span class="sr-only">Table of contents</span>
+				{!! ($page->getTableOfContents()) !!}
+			@endif
+		@else
+			<a href="{{ $item->route }}" class="block -ml-4 p-2 border-l-[0.325rem] border-transparent hover:bg-black/5 dark:hover:bg-black/10">{{ $item->title }}</a>
+		@endif
+	</li>
+	@endforeach
+</ul>

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

@@ -0,0 +1,7 @@
+<button id="sidebar-toggle" title="Toggle sidebar" aria-label="Toggle sidebar navigation menu"
+        @click="sidebarOpen = ! sidebarOpen" :class="{'active' : sidebarOpen}">
+    <span class="icon-bar dark:bg-white h-0" role="presentation"></span>
+    <span class="icon-bar dark:bg-white h-0" role="presentation"></span>
+    <span class="icon-bar dark:bg-white h-0" role="presentation"></span>
+    <span class="icon-bar dark:bg-white h-0" role="presentation"></span>
+</button>

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

@@ -1,17 +1,20 @@
-<ul id="sidebar" role="list">
-	@foreach ($sidebar->items as $item)
-	<li @class(['sidebar-navigation-item -ml-4 pl-4' , 'active bg-black/5 dark:bg-black/10'=> $item->route->getRouteKey() === $currentRoute->getRouteKey()])>
-			@if($item->route->getRouteKey() === $currentRoute->getRouteKey())
-		<a href="{{ $item->route }}" aria-current="true" class="-ml-4 p-2 block hover:bg-black/5 dark:hover:bg-black/10  text-indigo-600 dark:text-indigo-400 dark:font-medium border-l-[0.325rem] border-indigo-500 transition-colors duration-300	ease-in-out">{{
-			$item->title }}</a>
+<aside id="sidebar" x-cloak :class="sidebarOpen ? 'visible left-0' : 'invisible -left-64 md:visible md:left-0'"
+       class="bg-gray-100 dark:bg-gray-800 dark:text-gray-200 h-screen w-64 fixed z-30 md:block shadow-lg md:shadow-none transition-all duration-300">
+    <header id="sidebar-header" class="h-16">
+        @include('hyde::components.docs.sidebar-brand')
+    </header>
+    <nav id="sidebar-navigation" class="p-4 overflow-y-auto border-y border-gray-300 dark:border-[#1b2533] h-[calc(100vh_-_8rem)]">
+        @php
+            $sidebar = \Hyde\Framework\Models\DocumentationSidebar::create();
+        @endphp
 
-		@if(config('docs.table_of_contents.enabled', true))
-		<span class="sr-only">Table of contents</span>
-		{!! ($page->getTableOfContents()) !!}
-		@endif
-		@else
-		<a href="{{ $item->route }}" class="block -ml-4 p-2 border-l-[0.325rem] border-transparent hover:bg-black/5 dark:hover:bg-black/10">{{ $item->title }}</a>
-		@endif
-	</li>
-	@endforeach
-</ul>
+        @if($sidebar->hasGroups())
+            @include('hyde::components.docs.grouped-sidebar-navigation')
+        @else
+            @include('hyde::components.docs.sidebar-navigation')
+        @endif
+    </nav>
+    <footer id="sidebar-footer" class="h-16 absolute p-4 w-full bottom-0 left-0 text-center leading-8">
+        @include('hyde::components.docs.sidebar-footer')
+    </footer>
+</aside>