Merge pull request #2024 from hydephp/refactor-hydefront-styles-to-tailwind

[2.x] Refactor HydeFront styles to TailwindCSS

Author: emmadesilva

.github/workflows/continuous-integration.yml

@@ -109,41 +109,6 @@ jobs:
         run: php monorepo/scripts/tests/${{ matrix.script }}.php
 
 
-  build-hydefront-assets:
-
-    runs-on: ubuntu-latest
-    needs: run-smoke-tests
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          cache: 'npm'
-
-      - name: Install Node.js dependencies
-        working-directory: 'packages/hydefront'
-        run: npm ci
-
-      - name: Build assets for production
-        working-directory: 'packages/hydefront'
-        run: npm run build
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: 'hydefront'
-          path: 'packages/hydefront/dist'
-
-      - name: Commit changes
-        uses: EndBug/add-and-commit@v9
-        with:
-          add: 'packages/hydefront/dist'
-          message: 'Compile HydeFront assets for production'
-          new_branch: compile-hydefront
-
-
   build-tailwindcss:
 
     runs-on: ubuntu-latest

RELEASE_NOTES.md

@@ -98,6 +98,12 @@ This serves two purposes:
 - The realtime compiler now only serves assets from the media source directory (`_media`), and no longer checks the site output directory (`_site/media`) in https://github.com/hydephp/develop/pull/2012
 - **Breaking:** Replaced `--run-dev` and `--run-prod` build command flags with a single `--run-vite` flag that uses Vite to build assets in https://github.com/hydephp/develop/pull/2013
 - Moved the Vite build step to run before the site build to prevent duplicate media asset transfers in https://github.com/hydephp/develop/pull/2013
+- Ported the HydeSearch plugin used for the documentation search to be an Alpine.js implementation in https://github.com/hydephp/develop/pull/2029
+  - Renamed Blade component `hyde::components.docs.search-widget` to `hyde::components.docs.search-modal` in https://github.com/hydephp/develop/pull/2029
+  - Added support for customizing the search implementation by creating a `resources/js/HydeSearch.js` file in https://github.com/hydephp/develop/pull/2031
+- Normalized default Tailwind Typography Prose code block styles to match Torchlight's theme, ensuring consistent styling across Markdown and Torchlight code blocks in https://github.com/hydephp/develop/pull/2036.
+- Extracted CSS component partials in HydeFront in https://github.com/hydephp/develop/pull/2038
+- Replaced HydeFront styles with Tailwind in https://github.com/hydephp/develop/pull/2024
 
 ### Deprecated
 
@@ -121,6 +127,10 @@ This serves two purposes:
     - Removed `Hyde::siteMediaPath()` method replaced by `MediaFile::outputPath()` in https://github.com/hydephp/develop/pull/1911
 - Removed Laravel Mix as a dependency in https://github.com/hydephp/develop/pull/2010 (replaced with Vite)
 - **Breaking:** Removed `npm run prod` command (replaced with `npm run build`)
+- Removed CDN include for the HydeSearch plugin replaced by Alpine.js implementation in https://github.com/hydephp/develop/pull/2029
+  - This also removes the `<x-hyde::docs.search-input />` and `<x-hyde::docs.search-scripts />` Blade components, replaced by the new `<x-hyde::docs.hyde-search />` component.
+- Removed the `.torchlight-enabled` CSS class in https://github.com/hydephp/develop/pull/2036.
+- Removed The `hyde.css` file from HydeFront in https://github.com/hydephp/develop/pull/2037 as all styles were refactored to Tailwind in https://github.com/hydephp/develop/pull/2024.
 
 ### Fixed
 
@@ -138,6 +148,12 @@ This serves two purposes:
 - Simplified the asset file locator to only serve files from the media source directory in https://github.com/hydephp/develop/pull/2012
 - Added Vite HMR support in https://github.com/hydephp/develop/pull/2016
 
+#### HydeFront
+
+- Removed all Sass styles after porting everything to Tailwind in https://github.com/hydephp/develop/pull/2024
+- Removed the `hyde.css` file in https://github.com/hydephp/develop/pull/2037 as all its styles were refactored to Tailwind in https://github.com/hydephp/develop/pull/2024
+- Extracted CSS component partials in https://github.com/hydephp/develop/pull/2038
+
 ### Upgrade Guide
 
 Please see the "Breaking changes & upgrade guide" section below for more information.

_media/app.css

@@ -351,11 +351,13 @@ If you set this to false, Hyde will match the directory structure of the source
 
 ### Introduction
 
-The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget.
+Hyde includes a built-in search feature for documentation pages powered by Alpine.js. It consists of two parts:
+1. A search index generator that runs during the build command
+2. An Alpine.js powered frontend that provides the search interface
 
->info Tip: The HydeSearch plugin is what powers the search feature on this site! Why not [try it out](search)?
+>info Tip: The search feature is what powers the search on this site! Why not [try it out](search)?
 
-The search feature is enabled by default. You can disable it by removing the `DocumentationSearch` option from the Hyde `Features` config array.
+The search feature is enabled by default. You can disable it by removing the `DocumentationSearch` option from the Hyde `Features` config array:
 
 ```php
 // filepath: config/hyde.php
@@ -366,17 +368,27 @@ The search feature is enabled by default. You can disable it by removing the `Do
 
 ### Using the Search
 
-The search works by generating a JSON search index which the JavaScript plugin loads asynchronously.
+The search works by generating a JSON search index which Alpine.js loads asynchronously. There are two ways to access the search:
 
-Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`.
-
-The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialog using the keyboard shortcut `/`.
+1. A full-page search screen at `docs/search.html`
+2. A modal dialog accessible via a button in the documentation pages (similar to Algolia DocSearch). You can also open this dialog using the keyboard shortcut `/`
 
 >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config.
 
+### Search Features
+
+The search implementation includes:
+- Real-time search results as you type
+- Context highlighting of search terms
+- Match counting and search timing statistics
+- Dark mode support
+- Loading state indicators
+- Keyboard navigation support
+- Mobile-responsive design
+
 ### Hiding Pages from Indexing
 
-If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will not be added to the search index JSON file.
+For large pages like changelogs, you may want to exclude them from the search index. Add the page identifier to the `exclude_from_search` array in the docs config:
 
 ```php
 // filepath: config/docs.php
@@ -385,9 +397,11 @@ If you have a large page on your documentation site, like a changelog, you may w
 ]
 ```
 
+The page will remain accessible but won't appear in search results.
+
 ### Live Search with the Realtime Compiler
 
-The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it.
+When using `php hyde serve`, the Realtime Compiler automatically generates a fresh search index each time it's requested, ensuring your search results stay current during development.
 
 ## Automatic "Edit Page" Button
 

docs/creating-content/documentation-pages.md

@@ -13,7 +13,7 @@ With Hyde, **you don't have to do it**, in fact, you can skip this entire page i
 But as always with Hyde, you can customize everything if you want to.
 
 Hyde ships with a complete frontend using Blade views, TailwindCSS styles, and Alpine.js interactions.
-Some extra custom styles are made in the HydeFront package, which is pre-installed and bundled in the pre-configured Tailwind and Vite setup.
+Some extra component styles are organized into modular files in the HydeFront package, which is pre-installed and bundled in the pre-configured Tailwind and Vite setup.
 
 To get you started quickly, all the styles are already compiled and minified into `_media/app.css`,
 which will be copied to the `_site/media/app.css` directory when you run `php hyde build`.
@@ -26,7 +26,7 @@ No, it is optional. All the compiled styles that you need are already installed,
 
 ### When Should Assets be Compiled?
 
-The `_media/app.css` file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, as well as the HydeFront custom styles.
+The `_media/app.css` file that comes with Hyde contains TailwindCSS for all classes that are used in the default Blade views, as well as the HydeFront component styles.
 If you want to customize the Tailwind settings or add custom styles, you will need to recompile the styles yourself.
 
 For example, if you customize the Blade views and add new classes or add new classes in Blade-based pages, you may need to compile the assets yourself to get the new styles.
@@ -66,6 +66,12 @@ When running the `npm run dev/prod` command, Vite will compile the `resources/as
 
 The compiled assets will then be automatically copied to `_site/media` when you run `php hyde build`.
 
+### Customizing HydeFront Components
+
+HydeFront components are modular and can be easily customized to fit your needs.
+
+You can either remove the import of the component you want to customize and replace it with your own styles, or keep the import and add overriding styles after it (since CSS cascade order matters).
+
 ## Telling Hyde where to find assets
 
 ### Customizing the Blade templates

docs/creating-content/managing-assets.md

@@ -1,6 +1,6 @@
 # Internal HydeFront documentation
 
-## Building and creating a new HydeFront version
+## Creating a new HydeFront version
 
 ### Prerequisites
 
@@ -28,15 +28,14 @@ cd ../../
 npm link hydefront
 ```
 
-### Build and setup
+### Setup
 
 ```bash
 cd packages/hydefront
 git pull origin master
-npm run build
 ```
 
-### Build, version, and publish
+### Version and publish
 
 Head back to the monorepo root and run the following command to bump the version of the HydeFront package:
 

monorepo/docs/hydefront.md

@@ -0,0 +1,78 @@
+function initHydeSearch(searchIndexUrl) {
+    return {
+        searchIndex: [],
+        searchTerm: '',
+        results: [],
+        isLoading: true,
+        statusMessage: '',
+
+        async init() {
+            const response = await fetch(searchIndexUrl);
+            if (!response.ok) {
+                console.error('Could not load search index');
+                return;
+            }
+            this.searchIndex = await response.json();
+            this.isLoading = false;
+        },
+
+        search() {
+            const startTime = performance.now();
+            this.results = [];
+
+            if (!this.searchTerm) {
+                this.statusMessage = '';
+                window.dispatchEvent(new CustomEvent('search-results-updated', { detail: { hasResults: false } }));
+                return;
+            }
+
+            const searchResults = this.searchIndex.filter(entry =>
+                entry.title.toLowerCase().includes(this.searchTerm.toLowerCase()) ||
+                entry.content.toLowerCase().includes(this.searchTerm.toLowerCase())
+            );
+
+            if (searchResults.length === 0) {
+                this.statusMessage = 'No results found.';
+                window.dispatchEvent(new CustomEvent('search-results-updated', { detail: { hasResults: false } }));
+                return;
+            }
+
+            const totalMatches = searchResults.reduce((acc, result) => {
+                return acc + (result.content.match(new RegExp(this.searchTerm, 'gi')) || []).length;
+            }, 0);
+
+            searchResults.sort((a, b) => {
+                return (b.content.match(new RegExp(this.searchTerm, 'gi')) || []).length
+                    - (a.content.match(new RegExp(this.searchTerm, 'gi')) || []).length;
+            });
+
+            this.results = searchResults.map(result => {
+                const matches = (result.content.match(new RegExp(this.searchTerm, 'gi')) || []).length;
+                const context = this.getSearchContext(result.content);
+                return { ...result, matches, context };
+            });
+
+            const timeMs = Math.round((performance.now() - startTime) * 100) / 100;
+            this.statusMessage = `Found ${totalMatches} result${totalMatches !== 1 ? 's' : ''} in ${searchResults.length} pages. ~${timeMs}ms`;
+
+            window.dispatchEvent(new CustomEvent('search-results-updated', { detail: { hasResults: true } }));
+        },
+
+        getSearchContext(content) {
+            const searchTermPos = content.toLowerCase().indexOf(this.searchTerm.toLowerCase());
+            const sentenceStart = content.lastIndexOf('.', searchTermPos) + 1;
+            const sentenceEnd = content.indexOf('.', searchTermPos) + 1;
+            const sentence = content.substring(sentenceStart, sentenceEnd).trim();
+            const template = document.getElementById('search-highlight-template');
+
+            return sentence.replace(
+                new RegExp(this.searchTerm, 'gi'),
+                match => {
+                    const mark = template.content.querySelector('mark').cloneNode();
+                    mark.textContent = match;
+                    return mark.outerHTML;
+                }
+            );
+        }
+    };
+}

package-lock.json

@@ -5,7 +5,7 @@
 <article id="document" itemscope itemtype="https://schema.org/Article" @class([
         'mx-auto lg:ml-8 max-w-3xl p-12 md:px-16 max-w-[1000px] min-h-[calc(100vh_-_4rem)]',
         config('markdown.prose_classes', 'prose dark:prose-invert'),
-        'torchlight-enabled' => $article && $article->hasTorchlight()])>
+    ])>
     @yield('content')
 
     @if ($article)

packages/framework/resources/js/HydeSearch.js

@@ -0,0 +1,45 @@
+@props(['modal' => true])
+
+<div id="hyde-search" x-data="hydeSearch">
+    <template id="search-highlight-template">
+        <mark class="bg-yellow-400 dark:bg-yellow-300"></mark>
+    </template>
+
+    <div class="relative">
+        <input type="search" name="search" id="search-input" x-model="searchTerm" @input="search()" placeholder="Search..." autocomplete="off" autofocus
+                {{ $attributes->merge(['class' => 'w-full rounded text-base leading-normal bg-gray-100 dark:bg-gray-700 py-2 px-3']) }}
+        >
+
+        <div x-show="isLoading" class="absolute right-3 top-2.5">
+            <div class="animate-spin h-5 w-5 border-2 border-gray-500 rounded-full border-t-transparent"></div>
+        </div>
+    </div>
+
+    <div x-show="searchTerm" class="mt-4">
+        <p x-text="statusMessage" class="text-sm text-gray-600 dark:text-gray-400 mb-2 pb-2"></p>
+
+        <dl class="space-y-4 -mt-4 pl-2 -ml-2 {{ $modal ? 'max-h-[60vh] overflow-x-hidden overflow-y-auto' : '' }}">
+            <template x-for="result in results" :key="result.slug">
+                <div>
+                    <dt>
+                        <a :href="result.destination" x-text="result.title" class="text-indigo-600 dark:text-indigo-400 hover:underline font-medium"></a><span class="text-sm text-gray-600 dark:text-gray-400" x-text="`, ${result.matches} occurrence${result.matches !== 1 ? 's' : ''} found.`"></span>
+                    </dt>
+                    <dd class="mt-1 text-sm text-gray-700 dark:text-gray-300" x-html="result.context"></dd>
+                </div>
+            </template>
+        </dl>
+    </div>
+
+    <script>
+		{!! file_get_contents(file_exists(Hyde::path('resources/js/HydeSearch.js')) 
+			? Hyde::path('resources/js/HydeSearch.js')
+			: Hyde::vendorPath('resources/js/HydeSearch.js')
+		) !!}
+        
+        document.addEventListener('alpine:init', () => {
+            Alpine.data('hydeSearch', () => 
+                initHydeSearch('{{ Hyde::relativeLink(\Hyde\Framework\Features\Documentation\DocumentationSearchIndex::outputPath()) }}')
+            );
+        });
+    </script>
+</div>