From d00d8bac4e82172016ec111b4ec76f803fa872c9 Mon Sep 17 00:00:00 2001
From: Brian Talbot <hi.talbs@gmail.com>
Date: Wed, 24 Sep 2025 16:39:01 -0400
Subject: [PATCH] Docs: Update Header (#1490)

* updating color-scheme-selectors and theme-selectors
* abstracting repo links into github-icon-buttons
* adjusting responsive logo treatment
* moving version + beta info to sidebar
* removing unused + outdated header styling
* adding brand logo to sidebar
* updating `.brand-logo` styling
* abstracting search-trigger-button
---
 packages/webawesome/docs/_includes/base.njk   | 53 ++++++-------
 .../docs/_includes/color-scheme-selector.njk  | 44 ++++++-----
 .../docs/_includes/github-icon-buttons.njk    |  8 ++
 .../docs/_includes/search-trigger-button.njk  |  5 ++
 .../webawesome/docs/_includes/sidebar.njk     | 19 +++--
 .../docs/_includes/theme-selector.njk         | 33 +++++----
 .../docs/assets/scripts/color-scheme.js       | 19 ++++-
 .../webawesome/docs/assets/scripts/theme.js   | 48 ++++++++----
 .../webawesome/docs/assets/styles/docs.css    | 74 +++++++------------
 9 files changed, 170 insertions(+), 133 deletions(-)
 create mode 100644 packages/webawesome/docs/_includes/github-icon-buttons.njk
 create mode 100644 packages/webawesome/docs/_includes/search-trigger-button.njk

diff --git a/packages/webawesome/docs/_includes/base.njk b/packages/webawesome/docs/_includes/base.njk
index 1e28d901f..58279ae49 100644
--- a/packages/webawesome/docs/_includes/base.njk
+++ b/packages/webawesome/docs/_includes/base.njk
@@ -54,44 +54,29 @@
     >
         {% block pageHeader %}
           <header slot="header" class="wa-split">
-            {# Logo #}
-            <div id="docs-branding">
-              {# Nav toggle #}
+            {# Nav toggle #}
               <wa-button appearance="plain" size="small" data-toggle-nav>
                 <wa-icon name="bars" label="Toggle navigation"></wa-icon>
               </wa-button>
 
-              <a href="/" aria-label="Web Awesome">
-                <span class="wa-desktop-only">{% include "logo.njk" %}</span>
-                <span class="wa-mobile-only">{% include "logo-simple.njk" %}</span>
+              {# Logo - Desktop #}
+              <a class="brand-logo wa-desktop-only" href="/" aria-label="Web Awesome">
+                {% include "logo.njk" %}
               </a>
-              <small id="version-number" class="wa-desktop-only">{{ package.version }}</small>
-              <wa-badge variant="brand" appearance="filled" class="wa-desktop-only">Beta</wa-badge>
-            </div>
 
-            <div id="docs-toolbar" class="wa-cluster">
-              {# Desktop selectors #}
-              <div class="wa-desktop-only wa-cluster wa-gap-xs">
+            {#- Logo - mobile branding -#}
+            <a href="/" class="brand-logo wa-mobile-only" aria-label="Web Awesome">
+              {# Logo - Mobile #}
+              {% include "logo-simple.njk" %}
+            </a>
+
+            <div id="docs-toolbar" class="wa-cluster gap-s">
+              <div class="wa-desktop-only wa-cluster wa-gap-2xs">
                 {% include "theme-selector.njk" %}
                 {% include "color-scheme-selector.njk" %}
+                {% include "github-icon-buttons.njk" %}
               </div>
-
-              <wa-divider orientation="vertical" class="wa-desktop-only"></wa-divider>
-
-              <div id="github-buttons" class="wa-cluster wa-gap-xs">
-                <wa-button id="github-repo-button" href="https://github.com/shoelace-style/webawesome" rel="noopener noreferrer" target="_blank" appearance="filled" size="small">
-                  <wa-icon family="brands" name="github" label="GitHub"></wa-icon>
-                </wa-button>
-                <wa-tooltip for="github-repo-button" distance="2">GitHub</wa-tooltip>
-                <wa-button id="github-star-button" href="https://github.com/shoelace-style/webawesome/stargazers" rel="noopener noreferrer" target="_blank" appearance="filled" size="small">
-                  <wa-icon name="star" variant="regular" label="Star this repository"></wa-icon>
-                </wa-button>
-                <wa-tooltip for="github-star-button" distance="2">Star this repository</wa-tooltip>
-              </div>
-
-              <wa-divider orientation="vertical"></wa-divider>
-
-              {# Login #}
+              {#- Login -#}
               {% server "loginOrAvatar" %}
             </div>
           </header>
@@ -101,9 +86,13 @@
       {% if hasSidebar %}
         {# Mobile selectors #}
         <div class="wa-mobile-only" slot="navigation-header">
-          <div class="wa-cluster wa-gap-xs" style="flex-wrap: nowrap;">
-            {% include "theme-selector.njk" %}
-            {% include "color-scheme-selector.njk" %}
+          <div class="wa-cluster wa-gap-s">
+            <a class="brand-logo" href="/" aria-label="Web Awesome">{% include "logo-simple.njk" %}</a>
+            <div class="wa-cluster wa-gap-2xs" style="flex-wrap: nowrap;">
+              {% include "theme-selector.njk" %}
+              {% include "color-scheme-selector.njk" %}
+              {% include "github-icon-buttons.njk" %}
+            </div>
           </div>
         </div>
         <div slot="navigation" id="sidebar" class="docs-aside" data-remember-scroll>
diff --git a/packages/webawesome/docs/_includes/color-scheme-selector.njk b/packages/webawesome/docs/_includes/color-scheme-selector.njk
index d9aaea76a..0801ccbf4 100644
--- a/packages/webawesome/docs/_includes/color-scheme-selector.njk
+++ b/packages/webawesome/docs/_includes/color-scheme-selector.njk
@@ -1,25 +1,35 @@
-<wa-select class="color-scheme-selector" appearance="filled" value="auto" title="Press \ to toggle">
-  <wa-icon class="only-light" slot="start" name="sun-bright" variant="regular"></wa-icon>
-  <wa-icon class="only-dark" slot="start" name="moon-stars" variant="regular"></wa-icon>
-  <wa-option value="light">
-    <wa-icon slot="start" name="sun-bright" variant="regular"></wa-icon>
+<wa-dropdown class="color-scheme-selector" title="Press \ to toggle">
+  <wa-button slot="trigger" id="color-scheme-selector-trigger" appearance="plain">
+    <wa-icon class="only-light" name="sun-bright" variant="regular"></wa-icon>
+    <wa-icon class="only-dark" name="moon-stars" variant="regular"></wa-icon>
+  </wa-button>
+  <wa-dropdown-item value="light">
+    <wa-icon slot="icon" name="sun-bright" variant="regular"></wa-icon>
     Light
-  </wa-option>
-  <wa-option value="dark">
-    <wa-icon slot="start" name="moon-stars" variant="regular"></wa-icon>
+  </wa-dropdown-item>
+  <wa-dropdown-item value="dark">
+    <wa-icon slot="icon" name="moon-stars" variant="regular"></wa-icon>
     Dark
-  </wa-option>
+  </wa-dropdown-item>
   <wa-divider></wa-divider>
-  <wa-option value="auto">
-    <wa-icon class="only-light" slot="start" name="sun-bright" variant="regular"></wa-icon>
-    <wa-icon class="only-dark" slot="start" name="moon-stars" variant="regular"></wa-icon>
+  <wa-dropdown-item value="auto">
+    <wa-icon class="only-light" slot="icon" name="sun-bright" variant="regular"></wa-icon>
+    <wa-icon class="only-dark" slot="icon" name="moon-stars" variant="regular"></wa-icon>
     System
-  </wa-option>
-</wa-select>
+  </wa-dropdown-item>
+</wa-dropdown>
+<wa-tooltip for="color-scheme-selector-trigger" id="color-scheme-tooltip">Select Color Scheme</wa-tooltip>
 
 <script>
-  // Immediately set the correct value from storage
-  document.querySelectorAll('wa-select.color-scheme-selector').forEach(el => {
-    el.setAttribute('value', localStorage.getItem('color-scheme') || 'auto');
+  // Handle dropdown selection and trigger input event for color-scheme.js
+  document.querySelectorAll('wa-dropdown.color-scheme-selector').forEach(el => {
+    el.addEventListener('wa-select', (event) => {
+      const selectedValue = event.detail.item.value;
+
+      // Trigger input event for color-scheme.js
+      el.value = selectedValue;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+    });
   });
 </script>
+
diff --git a/packages/webawesome/docs/_includes/github-icon-buttons.njk b/packages/webawesome/docs/_includes/github-icon-buttons.njk
new file mode 100644
index 000000000..5d28e6ff9
--- /dev/null
+++ b/packages/webawesome/docs/_includes/github-icon-buttons.njk
@@ -0,0 +1,8 @@
+<wa-button id="github-repo-button" href="https://github.com/shoelace-style/webawesome" rel="noopener noreferrer" target="_blank" appearance="plain">
+  <wa-icon family="brands" name="github" label="View Repository on GitHub"></wa-icon>
+</wa-button>
+<wa-tooltip for="github-repo-button" distance="2">View on GitHub</wa-tooltip>
+<wa-button id="github-star-button" href="https://github.com/shoelace-style/webawesome/stargazers" rel="noopener noreferrer" target="_blank" appearance="plain">
+  <wa-icon name="star" variant="regular" label="Star Repository on GitHub"></wa-icon>
+</wa-button>
+<wa-tooltip for="github-star-button" distance="2">Star on GitHub</wa-tooltip>
diff --git a/packages/webawesome/docs/_includes/search-trigger-button.njk b/packages/webawesome/docs/_includes/search-trigger-button.njk
new file mode 100644
index 000000000..33ee36ee0
--- /dev/null
+++ b/packages/webawesome/docs/_includes/search-trigger-button.njk
@@ -0,0 +1,5 @@
+<wa-button id="search-trigger" appearance="outlined" size="small" data-search>
+  <wa-icon slot="start" name="magnifying-glass"></wa-icon>
+  Search the Docs for&hellip;
+  <kbd slot="end" class="wa-desktop-only">/</kbd>
+</wa-button>
diff --git a/packages/webawesome/docs/_includes/sidebar.njk b/packages/webawesome/docs/_includes/sidebar.njk
index c747b9951..17b5170e9 100644
--- a/packages/webawesome/docs/_includes/sidebar.njk
+++ b/packages/webawesome/docs/_includes/sidebar.njk
@@ -1,9 +1,5 @@
 {# Search #}
-<wa-button id="search-trigger" appearance="outlined" size="small" data-search>
-  <wa-icon slot="start" name="magnifying-glass"></wa-icon>
-  Search
-  <kbd slot="end" class="wa-desktop-only">/</kbd>
-</wa-button>
+{% include "search-trigger-button.njk" %}
 
 {# Getting started #}
 <h2>Getting Started</h2>
@@ -399,3 +395,16 @@
     <li><a href="/docs/tokens/component-groups/">Component Groups</a></li>
   </ul>
 </wa-details>
+
+<wa-divider style="--spacing: var(--wa-space-xl);"></wa-divider>
+
+<div class="wa-stack wa-gap-xs" id="colophon">
+  {% include "logo-simple.njk" %}
+  <div class="wa-cluster wa-gap-xs">
+    <h2 class="wa-heading-xs">Web Awesome</h2>
+    <wa-badge id="version-beta-badge" variant="orange" appearance="filled" style="font-size: var(--wa-font-size-2xs);">Beta</wa-badge>
+    <wa-tooltip for="version-beta-badge" distance="2" style="font-size: var(--wa-font-size-xs);">Here be freshly made Awesome&hellip; and possible dragons</wa-tooltip>
+  </div>
+  <p class="wa-caption-s">Version {{ package.version }}</p>
+  <p class="wa-caption-s">&copy; Fonticons, Inc.</p>
+</div>
diff --git a/packages/webawesome/docs/_includes/theme-selector.njk b/packages/webawesome/docs/_includes/theme-selector.njk
index 304c2e9ef..f6b4bb3b1 100644
--- a/packages/webawesome/docs/_includes/theme-selector.njk
+++ b/packages/webawesome/docs/_includes/theme-selector.njk
@@ -1,16 +1,18 @@
-<wa-select appearance="filled" size="small" value="default" class="theme-selector">
-  <wa-icon slot="start" name="paintbrush" variant="regular"></wa-icon>
+<wa-dropdown class="theme-selector" title="Select Theme">
+  <wa-button slot="trigger" id="theme-selector-trigger" appearance="plain">
+    <wa-icon name="paintbrush" variant="regular"></wa-icon>
+  </wa-button>
 
   {# Free themes #}
   {% for theme in themer.themes %}
     {% if not theme.isPro %}
-      <wa-option
+      <wa-dropdown-item
         value="{{ theme.filename | stripExtension }}"
         data-brand="{{ theme.colorBrand.color }}"
         data-palette="{{ theme.palette.filename | stripExtension }}"
       >
         {{ theme.name }}
-      </wa-option>
+      </wa-dropdown-item>
     {% endif %}
   {% endfor %}
 
@@ -18,24 +20,27 @@
   {% for theme in themer.themes %}
     {% if loop.first %}<wa-divider></wa-divider>{% endif %}
     {% if theme.isPro %}
-      <wa-option
+      <wa-dropdown-item
         value="{{ theme.filename | stripExtension }}"
         data-brand="{{ theme.colorBrand.color }}"
         data-palette="{{ theme.palette.filename | stripExtension }}"
       >
         {{ theme.name }}
-      </wa-option>
+      </wa-dropdown-item>
     {% endif %}
   {% endfor %}
-</wa-select>
+</wa-dropdown>
+<wa-tooltip for="theme-selector-trigger" id="theme-tooltip">Select Theme</wa-tooltip>
 
 <script>
-  // Immediately set the correct values from storage
-  document.querySelectorAll('wa-select.theme-selector').forEach(el => {
-    el.setAttribute('value', localStorage.getItem('theme') || 'default');
-  });
+  // Handle dropdown selection and trigger input event for theme.js
+  document.querySelectorAll('wa-dropdown.theme-selector').forEach(el => {
+    el.addEventListener('wa-select', (event) => {
+      const selectedValue = event.detail.item.value;
 
-  // Apply saved brand and palette classes
-  document.documentElement.classList.add(`wa-brand-${localStorage.getItem('brand') || 'blue'}`);
-  document.documentElement.classList.add(`wa-palette-${localStorage.getItem('palette') || 'default'}`);
+      // Trigger input event for theme.js
+      el.value = selectedValue;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+  });
 </script>
diff --git a/packages/webawesome/docs/assets/scripts/color-scheme.js b/packages/webawesome/docs/assets/scripts/color-scheme.js
index 0cd7c3ab3..506128faf 100644
--- a/packages/webawesome/docs/assets/scripts/color-scheme.js
+++ b/packages/webawesome/docs/assets/scripts/color-scheme.js
@@ -3,17 +3,30 @@ import { doViewTransition } from '../scripts/view-transitions.js';
 //
 // Updates the color scheme when a color scheme selector changes
 //
-function updateTheme(value) {
+async function updateTheme(value) {
   localStorage.setItem('color-scheme', value);
 
   const isDark = value === 'dark' || (value === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches);
 
-  doViewTransition(() => {
+  // Disable tooltip during transition
+  const tooltip = document.querySelector('#color-scheme-tooltip');
+  if (tooltip) {
+    tooltip.disabled = true;
+  }
+
+  await doViewTransition(() => {
     document.documentElement.classList.toggle('wa-dark', isDark);
   });
 
-  // Sync all selectors
+  // Sync all selectors and update tooltip
   document.querySelectorAll('.color-scheme-selector').forEach(el => (el.value = value));
+
+  // Update tooltip content and re-enable after transition completes
+  if (tooltip) {
+    const schemeText = value === 'light' ? 'Light' : value === 'dark' ? 'Dark' : 'System';
+    tooltip.textContent = schemeText;
+    tooltip.disabled = false;
+  }
 }
 
 // Handle changes
diff --git a/packages/webawesome/docs/assets/scripts/theme.js b/packages/webawesome/docs/assets/scripts/theme.js
index f7cf1210f..bb89e03d4 100644
--- a/packages/webawesome/docs/assets/scripts/theme.js
+++ b/packages/webawesome/docs/assets/scripts/theme.js
@@ -6,7 +6,20 @@ import { doViewTransition } from '../scripts/view-transitions.js';
 async function updateTheme(value, isInitialLoad = false) {
   const body = document.body;
 
+  // Get brand, palette, and theme name from the selected option
+  const themeSelector = document.querySelector('.theme-selector');
+  const selectedOption = themeSelector?.querySelector(`wa-dropdown-item[value="${value}"]`);
+  const brand = selectedOption?.getAttribute('data-brand') || 'blue';
+  const palette = selectedOption?.getAttribute('data-palette') || 'default';
+  const themeName = selectedOption?.textContent.trim() || 'Unknown';
+
   if (!isInitialLoad) {
+    // Disable tooltip during theme transition
+    const tooltip = document.querySelector('#theme-tooltip');
+    if (tooltip) {
+      tooltip.disabled = true;
+    }
+
     // Add fade-out class
     body.classList.add('theme-transitioning');
 
@@ -23,18 +36,11 @@ async function updateTheme(value, isInitialLoad = false) {
   }
 
   localStorage.setItem('theme', value);
-
-  // Get brand and palette from the selected option
-  const themeSelector = document.querySelector('.theme-selector');
-  const selectedOption = themeSelector?.querySelector(`wa-option[value="${value}"]`);
-  const brand = selectedOption?.getAttribute('data-brand') || 'blue';
-  const palette = selectedOption?.getAttribute('data-palette') || 'default';
-  const htmlElement = document.documentElement;
-
   localStorage.setItem('brand', brand);
   localStorage.setItem('palette', palette);
 
   // Update theme classes
+  const htmlElement = document.documentElement;
   const classesToRemove = Array.from(htmlElement.classList).filter(
     className =>
       className.startsWith('wa-theme-') || className.startsWith('wa-brand-') || className.startsWith('wa-palette-'),
@@ -42,7 +48,7 @@ async function updateTheme(value, isInitialLoad = false) {
   const themeStylesheet = document.getElementById('theme-stylesheet');
   const href = `/dist/styles/themes/${value}.css`;
 
-  doViewTransition(() => {
+  await doViewTransition(() => {
     // Update the theme
     if (themeStylesheet) {
       themeStylesheet.href = href;
@@ -56,16 +62,26 @@ async function updateTheme(value, isInitialLoad = false) {
     htmlElement.classList.add(`wa-palette-${palette}`);
 
     // Sync all theme selectors
-    document.querySelectorAll('.theme-selector').forEach(el => (el.value = value));
+    document.querySelectorAll('.theme-selector').forEach(el => {
+      el.value = value;
+      el.setAttribute('value', value);
+    });
+
+    // Update tooltip content to reflect the new theme
+    const tooltip = document.querySelector('#theme-tooltip');
+    if (tooltip) {
+      tooltip.textContent = `${themeName} Theme`;
+    }
   });
 
   if (!isInitialLoad) {
-    // Waiting for the stylesheet and all it's imports to load is tricky. Preloading doesn't work for most themes
-    // because applying the new stylesheet to the document, even without adding the `wa-theme-*` class, causes jank.
-    // Suggestions welcome.
-    setTimeout(() => {
-      body.classList.remove('theme-transitioning');
-    }, 500);
+    // Remove transition class and re-enable tooltip after view transition completes
+    body.classList.remove('theme-transitioning');
+
+    const tooltip = document.querySelector('#theme-tooltip');
+    if (tooltip) {
+      tooltip.disabled = false;
+    }
   }
 }
 
diff --git a/packages/webawesome/docs/assets/styles/docs.css b/packages/webawesome/docs/assets/styles/docs.css
index 4ce281a58..4476bcfb2 100644
--- a/packages/webawesome/docs/assets/styles/docs.css
+++ b/packages/webawesome/docs/assets/styles/docs.css
@@ -48,6 +48,16 @@ wa-page > header {
     line-height: 1;
   }
 
+  .brand-logo {
+    color: var(--wa-color-text-normal);
+    line-height: 1;
+  }
+
+  .brand-logo svg {
+    width: auto;
+    height: 1.75rem;
+  }
+
   wa-button[data-toggle-nav] {
     --text-color: currentColor;
     font-size: 1rem;
@@ -60,53 +70,11 @@ wa-page > header {
     }
   }
 
-  svg {
-    width: auto;
-    height: 1.75rem;
-  }
-
-  #docs-branding,
-  #docs-toolbar {
-    display: flex;
-    align-items: center;
-    gap: var(--wa-space-s);
-
-    .color-scheme-selector,
-    .theme-selector {
-      max-inline-size: 20ch;
+  /* increasing visual size of icons-only within buttons */
+  wa-button[appearance='plain'] {
+    > wa-icon {
+      font-size: round(1.125em, 1px);
     }
-
-    wa-divider:last-child {
-      display: none;
-    }
-  }
-
-  #github-buttons {
-    > wa-button {
-      &::part(base) {
-        color: var(--wa-color-on-quiet);
-        background-color: var(--wa-color-fill-quiet);
-      }
-      > wa-icon {
-        font-size: round(1.25em, 1px);
-      }
-    }
-
-    > wa-tooltip {
-      --wa-tooltip-arrow-size: 0;
-      font-size: var(--wa-font-size-xs);
-    }
-  }
-
-  #version-number {
-    color: var(--wa-color-text-quiet);
-    font-size: var(--wa-font-size-xs);
-    line-height: 1;
-    margin-block-start: var(--wa-space-2xs);
-  }
-  #version-number + wa-badge {
-    font-size: var(--wa-font-size-2xs);
-    text-transform: uppercase;
   }
 }
 
@@ -270,6 +238,20 @@ wa-page::part(menu) {
   scrollbar-width: thin;
 }
 
+/* smaller viewports-based navigation */
+wa-page > [slot='navigation-header'] {
+  padding: 0;
+
+  .brand-logo svg {
+    height: 1.25rem;
+  }
+
+  /* resetting font-weight of dropdown items in .title */
+  wa-dropdown {
+    font-weight: var(--wa-font-weight-normal);
+  }
+}
+
 wa-page[view='mobile'] :is([slot='navigation-header'], [slot='navigation']) {
   padding: 0;