From f096a5c0767eefccdd7b78e5a484c84675a88e6d Mon Sep 17 00:00:00 2001
From: "Mark A. Grondona" <mark.grondona@gmail.com>
Date: Wed, 15 Apr 2026 19:23:37 -0700
Subject: [PATCH 1/2] templates: add cross-project search via RTD Addons

Problem: sphinx_immaterial performs single-project client-side search
with no way to reach flux-framework subproject documentation. RTD
Addons (enabled by default since October 2024) provides native
cross-project search but was only accessible via the bottom-right
flyout, not the top-bar search input.

Override partials/search.html to render a search input that lacks
sphinx_immaterial's data-md-component attributes so the theme ignores
it, then dispatch the readthedocs-search-show custom event on
focus/click to open the RTD Addons cross-project search modal from
the header. Position the bar absolutely within .md-header__inner and
center it with left:50% + translate(-50%,-50%) so it stays centered
regardless of flex siblings. Falls back to sphinx_immaterial's
standard search for local builds where RTD Addons is absent.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 _static/custom.css              |  55 +++++++++++
 _templates/partials/search.html | 167 +++++++-------------------------
 2 files changed, 92 insertions(+), 130 deletions(-)

diff --git a/_static/custom.css b/_static/custom.css
index 1af7281c..376f2b52 100644
--- a/_static/custom.css
+++ b/_static/custom.css
@@ -1,3 +1,58 @@
+/* RTD search trigger: center the bar in the header and fix vertical alignment.
+   Without data-md-component="search", sphinx_immaterial does not manage this element,
+   so positioning and sizing must be set explicitly.
+   position:absolute + left:50%/translateX(-50%) centers the bar relative to the
+   header regardless of where the flex siblings land. */
+.md-header__inner {
+  position: relative;
+}
+.md-header .md-search {
+  display: flex;
+  align-items: center;
+  width: 20rem;
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  pointer-events: auto;
+}
+
+.md-header .md-search .md-search__inner,
+.md-header .md-search .md-search__form {
+  display: flex;
+  align-items: center;
+  width: 100%;
+}
+
+.md-header .md-search .md-search__input {
+  width: 100%;
+}
+
+/* Sync RTD Addons search modal colors with sphinx_immaterial's slate (dark) scheme.
+   RTD Addons modal defaults to light mode; these overrides make it follow the
+   site's dark mode toggle by mapping to sphinx_immaterial's own CSS variables. */
+body[data-md-color-scheme="slate"] {
+  --readthedocs-search-color: var(--md-default-fg-color);
+  --readthedocs-search-link-color: var(--md-default-fg-color);
+  --readthedocs-search-content-background-color: var(--md-default-bg-color);
+  --readthedocs-search-input-background-color: var(--md-default-bg-color--light);
+  --readthedocs-search-footer-background-color: var(--md-default-bg-color--light);
+  --readthedocs-search-footer-color: var(--md-default-fg-color);
+  --readthedocs-search-footer-code-background-color: var(--md-default-bg-color--lighter);
+  --readthedocs-search-content-border-color: var(--md-default-fg-color--lightest);
+  --readthedocs-search-filters-border-color: var(--md-default-fg-color--lightest);
+  --readthedocs-search-result-border-color: var(--md-default-fg-color--lightest);
+  --readthedocs-search-footer-code-border-color: var(--md-default-fg-color--lightest);
+  --readthedocs-search-result-active-background-color: var(--md-default-bg-color--light);
+  --readthedocs-search-result-color: var(--md-default-fg-color--light);
+  --readthedocs-search-result-heading-color: var(--md-default-fg-color);
+  --readthedocs-search-result-subheading-color: var(--md-default-fg-color--light);
+  --readthedocs-search-result-icon-color: var(--md-default-fg-color--light);
+  --readthedocs-search-badge-color: var(--md-default-fg-color);
+  --readthedocs-search-badge-background-color: var(--md-default-bg-color--light);
+  --readthedocs-search-backdrop-color: rgba(0, 0, 0, 0.7);
+}
+
 .o-tooltip--left:after{
     font-size: 0.8rem;
 }
diff --git a/_templates/partials/search.html b/_templates/partials/search.html
index f0290d47..46a03084 100644
--- a/_templates/partials/search.html
+++ b/_templates/partials/search.html
@@ -1,153 +1,56 @@
-{#- Custom search that uses ReadTheDocs server-side API for cross-project searching -#}
+{#- On RTD: forward search interactions to RTD Addons, which provides cross-project
+    search across all flux-framework subprojects natively. Off RTD: fall back to
+    sphinx_immaterial's default client-side search. -#}
 {% if on_rtd %}
-  {# On ReadTheDocs, use server-side search API which supports cross-project search #}
-  <div class="md-search" data-md-component="search" role="dialog">
+  <div class="md-search" role="dialog">
     <label class="md-search__overlay" for="__search"></label>
     <div class="md-search__inner" role="search">
-      <form class="md-search__form" name="search" id="rtd-search-form">
-        <input type="text" name="q" class="md-search__input" placeholder="Search across all Flux docs" aria-label="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
+      <form class="md-search__form" name="search">
+        <input type="text"
+               class="md-search__input"
+               placeholder="Search across all Flux docs"
+               aria-label="Search"
+               autocapitalize="off"
+               autocorrect="off"
+               autocomplete="off"
+               spellcheck="false"
+               style="cursor: pointer"
+               readonly>
         <label class="md-search__icon md-icon" for="__search">
           {% set icon = config.theme.icon.search or "material/magnify" %}
           {% include ".icons/" ~ icon ~ ".svg" %}
           {% set icon = config.theme.icon.previous or "material/arrow-left" %}
           {% include ".icons/" ~ icon ~ ".svg" %}
         </label>
-        <nav class="md-search__options" aria-label="Search">
-          <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
-            {% set icon = config.theme.icon.close or "material/close" %}
-            {% include ".icons/" ~ icon ~ ".svg" %}
-          </button>
-        </nav>
       </form>
-      <div class="md-search__output">
-        <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
-          <div class="md-search-result" data-md-component="search-result">
-            <div class="md-search-result__meta">
-              Type to search across all Flux documentation
-            </div>
-            <ol class="md-search-result__list" role="presentation" id="rtd-search-results"></ol>
-          </div>
-        </div>
-      </div>
     </div>
   </div>
-
   <script>
   (function() {
-    const form = document.getElementById('rtd-search-form');
-    const input = form.querySelector('input[name="q"]');
-    const resultsContainer = document.getElementById('rtd-search-results');
-    const metaContainer = resultsContainer.previousElementSibling;
-    let searchTimeout;
-
-    // ReadTheDocs API endpoint - use relative path to avoid CORS issues
-    // RTD proxies the API at /_/api/v3/ on the same domain
-    const RTD_SEARCH_API = '/_/api/v3/search/';
-    const PROJECT_SLUG = 'flux-framework';
-    const SEARCH_SUBPROJECTS = true;
-
-    input.addEventListener('input', function(e) {
-      clearTimeout(searchTimeout);
-      const query = e.target.value.trim();
-
-      if (query.length < 2) {
-        metaContainer.textContent = 'Type to search across all Flux documentation';
-        resultsContainer.innerHTML = '';
-        return;
-      }
-
-      metaContainer.textContent = 'Searching...';
-
-      searchTimeout = setTimeout(() => {
-        searchRTD(query);
-      }, 300);
-    });
-
-    async function searchRTD(query) {
-      try {
-        let searchUrl = `${RTD_SEARCH_API}?q=${encodeURIComponent(query)}&project=${PROJECT_SLUG}`;
-        if (SEARCH_SUBPROJECTS) {
-          searchUrl += '&subprojects=true';
-        }
-
-        const response = await fetch(searchUrl);
-        const data = await response.json();
-
-        displayResults(data.results || [], query);
-      } catch (err) {
-        console.error('Search error:', err);
-        metaContainer.textContent = 'Search error occurred';
-        resultsContainer.innerHTML = '';
-      }
-    }
-
-    function displayResults(results, query) {
-      if (results.length === 0) {
-        metaContainer.textContent = `No results found for "${query}"`;
-        resultsContainer.innerHTML = '';
-        return;
-      }
-
-      metaContainer.textContent = `${results.length} result${results.length !== 1 ? 's' : ''} found`;
-
-      // Sort by relevance score if available
-      results.sort((a, b) => (b.score || 0) - (a.score || 0));
-
-      resultsContainer.innerHTML = results.slice(0, 20).map(result => {
-        const project = result.project || 'flux-framework';
-        const projectLabel = project.replace('flux-', '');
-
-        return `
-          <li class="md-search-result__item">
-            <a href="${result.link || result.path}" class="md-search-result__link" tabindex="-1">
-              <article class="md-search-result__article md-search-result__article--document">
-                <h1 class="md-search-result__title">${highlightText(result.title, query)}</h1>
-                <p class="md-search-result__teaser">
-                  <span class="md-search-result__project">[${projectLabel}]</span>
-                  ${result.blocks && result.blocks[0] ? highlightText(result.blocks[0].content.substring(0, 150), query) + '...' : ''}
-                </p>
-              </article>
-            </a>
-          </li>
-        `;
-      }).join('');
-    }
-
-    function highlightText(text, query) {
-      if (!text) return '';
-      const regex = new RegExp(`(${query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi');
-      return text.replace(regex, '<mark>$1</mark>');
-    }
-
-    form.addEventListener('submit', function(e) {
+    // Dispatch the RTD Addons event that opens the cross-project search modal.
+    // The input has no data-md-component attributes so sphinx_immaterial ignores it;
+    // all search interactions are forwarded to RTD Addons instead.
+    const form = document.currentScript.previousElementSibling;
+    const input = form.querySelector('input');
+    function showRTDSearch(e) {
       e.preventDefault();
-    });
+      document.dispatchEvent(new CustomEvent('readthedocs-search-show', { bubbles: true }));
+    }
+    input.addEventListener('focus', showRTDSearch);
+    input.addEventListener('click', showRTDSearch);
   })();
   </script>
-
-  <style>
-  .md-search-result__project {
-    display: inline-block;
-    font-weight: bold;
-    font-size: 0.7rem;
-    padding: 0.1em 0.4em;
-    margin-right: 0.5em;
-    background: var(--md-primary-fg-color);
-    color: var(--md-primary-bg-color);
-    border-radius: 0.2rem;
-  }
-  .md-search-result__teaser mark {
-    background: var(--md-accent-fg-color);
-    color: var(--md-accent-bg-color);
-  }
-  </style>
 {% else %}
-  {# Fallback to theme's default search when not on RTD #}
+  {# Fallback to sphinx_immaterial's default search for local builds #}
   <div class="md-search" data-md-component="search" role="dialog">
     <label class="md-search__overlay" for="__search"></label>
     <div class="md-search__inner" role="search">
       <form class="md-search__form" name="search">
-        <input type="text" class="md-search__input" name="query" aria-label="{{ lang.t('search.placeholder') }}" placeholder="{{ lang.t('search.placeholder') }}" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
+        <input type="text" class="md-search__input" name="query"
+               aria-label="{{ lang.t('search.placeholder') }}"
+               placeholder="{{ lang.t('search.placeholder') }}"
+               autocapitalize="off" autocorrect="off" autocomplete="off"
+               spellcheck="false" data-md-component="search-query" required>
         <label class="md-search__icon md-icon" for="__search">
           {% set icon = config.theme.icon.search or "material/magnify" %}
           {% include ".icons/" ~ icon ~ ".svg" %}
@@ -156,12 +59,16 @@ <h1 class="md-search-result__title">${highlightText(result.title, query)}</h1>
         </label>
         <nav class="md-search__options" aria-label="{{ lang.t('search') }}">
           {% if "search.share" in features %}
-            <a href="javascript:void(0)" class="md-search__icon md-icon" title="{{ lang.t('search.share') }}" aria-label="{{ lang.t('search.share') }}" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
+            <a href="javascript:void(0)" class="md-search__icon md-icon"
+               title="{{ lang.t('search.share') }}" aria-label="{{ lang.t('search.share') }}"
+               data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
               {% set icon = config.theme.icon.share or "material/share-variant" %}
               {% include ".icons/" ~ icon ~ ".svg" %}
             </a>
           {% endif %}
-          <button type="reset" class="md-search__icon md-icon" title="{{ lang.t('search.reset') }}" aria-label="{{ lang.t('search.reset') }}" tabindex="-1">
+          <button type="reset" class="md-search__icon md-icon"
+                  title="{{ lang.t('search.reset') }}" aria-label="{{ lang.t('search.reset') }}"
+                  tabindex="-1">
             {% set icon = config.theme.icon.close or "material/close" %}
             {% include ".icons/" ~ icon ~ ".svg" %}
           </button>

From 31c75ecceefcc9d0cd2efb012654dcada4d743e2 Mon Sep 17 00:00:00 2001
From: "Mark A. Grondona" <mark.grondona@gmail.com>
Date: Thu, 16 Apr 2026 06:33:06 -0700
Subject: [PATCH 2/2] templates,css: fix RTD Addons search modal dark mode

Problem: The RTD Addons search modal uses light mode regardless
of the site's color scheme. CSS custom properties set on body
are insufficient because the shadow DOM's :host rules override
inherited values in the cascade. The .filters-title element inside
the shadow root also uses a hardcoded background: rgb(252,252,252)
that no external custom property could reach.

Set all --readthedocs-search-* overrides directly on the
readthedocs-search host element so light-DOM author styles beat :host
rules. For elements with hardcoded values, inject a <style> into the
shadow root when the slate scheme is active; CSS custom properties
pierce the shadow boundary so the injected rule can reference
--readthedocs-search-content-background-color. A MutationObserver
re-applies the style when the user toggles the color scheme.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 _static/custom.css              |  8 ++++---
 _templates/partials/search.html | 39 +++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/_static/custom.css b/_static/custom.css
index 376f2b52..a764b783 100644
--- a/_static/custom.css
+++ b/_static/custom.css
@@ -29,9 +29,10 @@
 }
 
 /* Sync RTD Addons search modal colors with sphinx_immaterial's slate (dark) scheme.
-   RTD Addons modal defaults to light mode; these overrides make it follow the
-   site's dark mode toggle by mapping to sphinx_immaterial's own CSS variables. */
-body[data-md-color-scheme="slate"] {
+   Variables must be set directly on the readthedocs-search element, not on body —
+   light-DOM styles on the host element override the shadow DOM's :host rules,
+   whereas inherited values from body lose to :host. */
+body[data-md-color-scheme="slate"] readthedocs-search {
   --readthedocs-search-color: var(--md-default-fg-color);
   --readthedocs-search-link-color: var(--md-default-fg-color);
   --readthedocs-search-content-background-color: var(--md-default-bg-color);
@@ -40,6 +41,7 @@ body[data-md-color-scheme="slate"] {
   --readthedocs-search-footer-color: var(--md-default-fg-color);
   --readthedocs-search-footer-code-background-color: var(--md-default-bg-color--lighter);
   --readthedocs-search-content-border-color: var(--md-default-fg-color--lightest);
+  --readthedocs-search-filters-background-color: var(--md-default-bg-color--light);
   --readthedocs-search-filters-border-color: var(--md-default-fg-color--lightest);
   --readthedocs-search-result-border-color: var(--md-default-fg-color--lightest);
   --readthedocs-search-footer-code-border-color: var(--md-default-fg-color--lightest);
diff --git a/_templates/partials/search.html b/_templates/partials/search.html
index 46a03084..5502e4ec 100644
--- a/_templates/partials/search.html
+++ b/_templates/partials/search.html
@@ -38,6 +38,45 @@
     }
     input.addEventListener('focus', showRTDSearch);
     input.addEventListener('click', showRTDSearch);
+
+    // Fix dark mode in the RTD Addons search modal. The shadow DOM uses hardcoded
+    // background colors for some elements (e.g. .filters-title) that our external
+    // CSS custom properties cannot override. We inject a <style> into the shadow
+    // root; CSS custom properties DO pierce the shadow boundary, so we can still
+    // reference our --readthedocs-search-* variables from the injected style.
+    const DARK_STYLE_ID = 'flux-rtd-dark';
+    function injectDarkStyle(shadowRoot) {
+      if (shadowRoot.getElementById(DARK_STYLE_ID)) return;
+      const style = document.createElement('style');
+      style.id = DARK_STYLE_ID;
+      style.textContent = [
+        /* filters-title floats as a label over the border — needs content bg */
+        '.filters-title { background: var(--readthedocs-search-content-background-color) !important; }',
+      ].join('\n');
+      shadowRoot.appendChild(style);
+    }
+    function removeDarkStyle(shadowRoot) {
+      const existing = shadowRoot.getElementById(DARK_STYLE_ID);
+      if (existing) existing.remove();
+    }
+    function syncDarkMode() {
+      const rtdSearch = document.querySelector('readthedocs-search');
+      if (!rtdSearch || !rtdSearch.shadowRoot) return;
+      const isDark = document.body.getAttribute('data-md-color-scheme') === 'slate';
+      isDark ? injectDarkStyle(rtdSearch.shadowRoot) : removeDarkStyle(rtdSearch.shadowRoot);
+    }
+    // Watch for the readthedocs-search element to be added to the DOM.
+    const domObserver = new MutationObserver(function(_, obs) {
+      if (document.querySelector('readthedocs-search')) {
+        obs.disconnect();
+        syncDarkMode();
+        // Re-sync whenever the user toggles the color scheme.
+        new MutationObserver(syncDarkMode).observe(document.body, {
+          attributes: true, attributeFilter: ['data-md-color-scheme']
+        });
+      }
+    });
+    domObserver.observe(document.body, { childList: true, subtree: true });
   })();
   </script>
 {% else %}