From 4779d18bb05a7d1cee7a3da73cc39e5be1152513 Mon Sep 17 00:00:00 2001
From: Tim Paine <3105306+timkpaine@users.noreply.github.com>
Date: Fri, 23 Oct 2026 13:32:13 -0400
Subject: [PATCH] Add hover tooltips to theme controls

Signed-off-by: Tim Paine <3105306+timkpaine@users.noreply.github.com>
---
 sphinx_fuma/layout.html              |  2 +-
 sphinx_fuma/partials/llms.html       |  2 +-
 sphinx_fuma/partials/pagination.html |  4 ++--
 sphinx_fuma/partials/sidebar.html    | 20 ++++++++++----------
 sphinx_fuma/partials/subnav.html     | 10 +++++-----
 sphinx_fuma/partials/toc.html        |  4 ++--
 sphinx_fuma/tests/test_llms.py       |  2 +-
 sphinx_fuma/tests/test_theme.py      |  2 +-
 8 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/sphinx_fuma/layout.html b/sphinx_fuma/layout.html
index 1c10b49..10f229e 100644
--- a/sphinx_fuma/layout.html
+++ b/sphinx_fuma/layout.html
@@ -37,7 +37,7 @@
 
   {%- if fuma_toc %}
   <div id="fd-toc-popover">
-    <button type="button" class="fd-toc-trigger" aria-expanded="false" aria-controls="fd-toc-mobile">
+    <button type="button" class="fd-toc-trigger" aria-expanded="false" aria-controls="fd-toc-mobile" title="{{ _('On this page') }}">
       {{ icons.list() }}<span>{{ _('On this page') }}</span>{{ icons.chevron_down() }}
     </button>
     <div id="fd-toc-mobile" hidden>{% include "partials/toc-list.html" %}</div>
diff --git a/sphinx_fuma/partials/llms.html b/sphinx_fuma/partials/llms.html
index c33f0b5..8b6d6df 100644
--- a/sphinx_fuma/partials/llms.html
+++ b/sphinx_fuma/partials/llms.html
@@ -6,7 +6,7 @@
   </summary>
   <nav class="fd-llms-menu" aria-label="{{ _('LLM documentation') }}">
     {%- for link in fuma_llms_links %}
-    <a href="{{ link.url|e }}">{{ link.title }}</a>
+    <a href="{{ link.url|e }}" title="{{ link.title|e }}">{{ link.title }}</a>
     {%- endfor %}
   </nav>
 </details>
diff --git a/sphinx_fuma/partials/pagination.html b/sphinx_fuma/partials/pagination.html
index fe245b7..b29583f 100644
--- a/sphinx_fuma/partials/pagination.html
+++ b/sphinx_fuma/partials/pagination.html
@@ -2,7 +2,7 @@
 {%- if prev or next %}
 <nav class="fd-pagination" aria-label="{{ _('Pagination') }}">
   {%- if prev %}
-  <a class="fd-pagination-card fd-pagination-prev" href="{{ prev.link|e }}">
+  <a class="fd-pagination-card fd-pagination-prev" href="{{ prev.link|e }}" title="{{ _('Previous') }}: {{ prev.title|striptags|e }}">
     {{ icons.chevron_left() }}
     <span class="fd-pagination-text">
       <span class="fd-pagination-label">{{ _('Previous') }}</span>
@@ -12,7 +12,7 @@
   {%- else %}<span></span>{% endif %}
 
   {%- if next %}
-  <a class="fd-pagination-card fd-pagination-next" href="{{ next.link|e }}">
+  <a class="fd-pagination-card fd-pagination-next" href="{{ next.link|e }}" title="{{ _('Next') }}: {{ next.title|striptags|e }}">
     <span class="fd-pagination-text">
       <span class="fd-pagination-label">{{ _('Next') }}</span>
       <span class="fd-pagination-title">{{ next.title|striptags|e }}</span>
diff --git a/sphinx_fuma/partials/sidebar.html b/sphinx_fuma/partials/sidebar.html
index 930cac0..6e8335c 100644
--- a/sphinx_fuma/partials/sidebar.html
+++ b/sphinx_fuma/partials/sidebar.html
@@ -6,7 +6,7 @@
   <li class="fd-tree-item">
     {%- if entry.children %}
     <details class="fd-folder"{% if entry.active or entry.depth <= fuma_default_open_level %} open{% endif %}>
-      <summary class="fd-folder-summary">
+      <summary class="fd-folder-summary" title="{{ _('Toggle section') }}: {{ entry.title|e }}">
         <a class="fd-link{% if entry.current %} fd-current{% endif %}" href="{{ entry.url|e }}"{% if entry.external %} target="_blank" rel="noopener"{% endif %}>
           {%- if entry.icon %}<span class="fd-link-icon">{{ icons.named(entry.icon) }}</span>{% endif %}
           <span class="fd-link-text">{{ entry.title }}</span>
@@ -31,18 +31,18 @@
   <div class="fd-sidebar-header">
     <div class="fd-sidebar-brand-row">
       {%- include "partials/brand.html" %}
-      <button type="button" class="fd-icon-button fd-sidebar-collapse" aria-label="{{ _('Collapse sidebar') }}">{{ icons.panel_left() }}</button>
+      <button type="button" class="fd-icon-button fd-sidebar-collapse" aria-label="{{ _('Collapse sidebar') }}" title="{{ _('Collapse sidebar') }}">{{ icons.panel_left() }}</button>
     </div>
 
     {%- if fuma_search %}
-    <button type="button" class="fd-search-trigger" data-fd-search-open>
+    <button type="button" class="fd-search-trigger" data-fd-search-open title="{{ _('Search') }}">
       {{ icons.search() }}<span>{{ _('Search') }}</span><kbd class="fd-kbd">/</kbd>
     </button>
     {%- endif %}
 
     {%- if fuma_tabs %}
     <details class="fd-navigator">
-      <summary class="fd-navigator-trigger">
+      <summary class="fd-navigator-trigger" title="{{ _('Switch section') }}">
         <span class="fd-navigator-icon">{{ icons.named(fuma_active_tab.icon or 'layers') }}</span>
         <span class="fd-navigator-label">
           <span class="fd-navigator-title">{{ fuma_active_tab.title }}</span>
@@ -52,7 +52,7 @@
       </summary>
       <div class="fd-navigator-menu">
         {%- for tab in fuma_tabs %}
-        <a class="fd-navigator-option{% if tab.active %} fd-current{% endif %}" href="{{ tab.url|e }}">
+        <a class="fd-navigator-option{% if tab.active %} fd-current{% endif %}" href="{{ tab.url|e }}" title="{{ tab.title|e }}">
           <span class="fd-navigator-icon">{{ icons.named(tab.icon or 'layers') }}</span>
           <span class="fd-navigator-label">
             <span class="fd-navigator-title">{{ tab.title }}</span>
@@ -81,18 +81,18 @@
   <div class="fd-sidebar-footer">
     <div class="fd-toolbar">
       {%- for link in fuma_nav_links %}
-      <a class="fd-toolbar-item" href="{{ link.url|e }}"{% if link.external %} target="_blank" rel="noopener"{% endif %}{% if link.icon %} aria-label="{{ link.title|e }}" title="{{ link.title|e }}"{% endif %}>{% if link.icon %}{{ icons.named(link.icon, "fd-icon-" ~ link.icon) }}{% else %}{{ link.title }}{% endif %}</a>
+      <a class="fd-toolbar-item" href="{{ link.url|e }}"{% if link.external %} target="_blank" rel="noopener"{% endif %} title="{{ link.title|e }}"{% if link.icon %} aria-label="{{ link.title|e }}"{% endif %}>{% if link.icon %}{{ icons.named(link.icon, "fd-icon-" ~ link.icon) }}{% else %}{{ link.title }}{% endif %}</a>
       {%- endfor %}
       {%- if fuma_github_url %}
-      <a class="fd-toolbar-item" href="{{ fuma_github_url|e }}" target="_blank" rel="noopener" aria-label="GitHub">{{ icons.github() }}</a>
+      <a class="fd-toolbar-item" href="{{ fuma_github_url|e }}" target="_blank" rel="noopener" aria-label="GitHub" title="GitHub">{{ icons.github() }}</a>
       {%- endif %}
       {%- include "partials/llms.html" %}
       <div class="fd-theme-switch" role="group" aria-label="{{ _('Theme') }}">
-        <button type="button" class="fd-theme-option" data-fd-theme="light" aria-label="{{ _('Light theme') }}">{{ icons.sun() }}</button>
-        <button type="button" class="fd-theme-option" data-fd-theme="dark" aria-label="{{ _('Dark theme') }}">{{ icons.moon() }}</button>
+        <button type="button" class="fd-theme-option" data-fd-theme="light" aria-label="{{ _('Light theme') }}" title="{{ _('Light theme') }}">{{ icons.sun() }}</button>
+        <button type="button" class="fd-theme-option" data-fd-theme="dark" aria-label="{{ _('Dark theme') }}" title="{{ _('Dark theme') }}">{{ icons.moon() }}</button>
       </div>
     </div>
   </div>
 </aside>
-<button type="button" id="fd-sidebar-restore" class="fd-icon-button" aria-label="{{ _('Expand sidebar') }}">{{ icons.panel_left() }}</button>
+<button type="button" id="fd-sidebar-restore" class="fd-icon-button" aria-label="{{ _('Expand sidebar') }}" title="{{ _('Expand sidebar') }}">{{ icons.panel_left() }}</button>
 <div class="fd-sidebar-scrim" hidden></div>
diff --git a/sphinx_fuma/partials/subnav.html b/sphinx_fuma/partials/subnav.html
index c3489b4..560e874 100644
--- a/sphinx_fuma/partials/subnav.html
+++ b/sphinx_fuma/partials/subnav.html
@@ -2,7 +2,7 @@
 {#- Top bar: mobile only in the docs layout, always present in the notebook layout. -#}
 <header id="fd-subnav">
   <div class="fd-subnav-inner">
-    <button type="button" class="fd-icon-button fd-sidebar-toggle" aria-controls="fd-sidebar" aria-expanded="false" aria-label="{{ _('Toggle navigation') }}">
+    <button type="button" class="fd-icon-button fd-sidebar-toggle" aria-controls="fd-sidebar" aria-expanded="false" aria-label="{{ _('Toggle navigation') }}" title="{{ _('Toggle navigation') }}">
       {{ icons.menu() }}
     </button>
 
@@ -11,20 +11,20 @@
     {%- if fuma_nav_links %}
     <nav class="fd-nav-links" aria-label="{{ _('Site') }}">
       {%- for link in fuma_nav_links %}
-      <a{% if link.icon %} class="fd-icon-button"{% endif %} href="{{ link.url|e }}"{% if link.external %} target="_blank" rel="noopener"{% endif %}{% if link.icon %} aria-label="{{ link.title|e }}" title="{{ link.title|e }}"{% endif %}>{% if link.icon %}{{ icons.named(link.icon, "fd-icon-" ~ link.icon) }}{% else %}{{ link.title }}{% endif %}</a>
+      <a{% if link.icon %} class="fd-icon-button"{% endif %} href="{{ link.url|e }}"{% if link.external %} target="_blank" rel="noopener"{% endif %} title="{{ link.title|e }}"{% if link.icon %} aria-label="{{ link.title|e }}"{% endif %}>{% if link.icon %}{{ icons.named(link.icon, "fd-icon-" ~ link.icon) }}{% else %}{{ link.title }}{% endif %}</a>
       {%- endfor %}
     </nav>
     {%- endif %}
 
     <div class="fd-nav-actions">
       {%- if fuma_search %}
-      <button type="button" class="fd-icon-button" data-fd-search-open aria-label="{{ _('Search') }}">{{ icons.search() }}</button>
+      <button type="button" class="fd-icon-button" data-fd-search-open aria-label="{{ _('Search') }}" title="{{ _('Search') }}">{{ icons.search() }}</button>
       {%- endif %}
       {%- if fuma_github_url %}
-      <a class="fd-icon-button" href="{{ fuma_github_url|e }}" target="_blank" rel="noopener" aria-label="GitHub">{{ icons.github() }}</a>
+      <a class="fd-icon-button" href="{{ fuma_github_url|e }}" target="_blank" rel="noopener" aria-label="GitHub" title="GitHub">{{ icons.github() }}</a>
       {%- endif %}
       {%- include "partials/llms.html" %}
-      <button type="button" class="fd-icon-button fd-theme-toggle" aria-label="{{ _('Toggle theme') }}">
+      <button type="button" class="fd-icon-button fd-theme-toggle" aria-label="{{ _('Toggle theme') }}" title="{{ _('Toggle theme') }}">
         {{ icons.sun("fd-icon-light") }}{{ icons.moon("fd-icon-dark") }}
       </button>
     </div>
diff --git a/sphinx_fuma/partials/toc.html b/sphinx_fuma/partials/toc.html
index 8a25efa..5dced7b 100644
--- a/sphinx_fuma/partials/toc.html
+++ b/sphinx_fuma/partials/toc.html
@@ -15,10 +15,10 @@
   {%- if fuma_edit_url or (show_source and has_source and sourcename) %}
   <div class="fd-toc-actions">
     {%- if fuma_edit_url %}
-    <a class="fd-toc-action" href="{{ fuma_edit_url }}" target="_blank" rel="noopener">{{ icons.pencil() }}<span>{{ _('Edit this page') }}</span></a>
+    <a class="fd-toc-action" href="{{ fuma_edit_url }}" target="_blank" rel="noopener" title="{{ _('Edit this page') }}">{{ icons.pencil() }}<span>{{ _('Edit this page') }}</span></a>
     {%- endif %}
     {%- if show_source and has_source and sourcename %}
-    <a class="fd-toc-action" href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow">{{ icons.file() }}<span>{{ _('View source') }}</span></a>
+    <a class="fd-toc-action" href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow" title="{{ _('View source') }}">{{ icons.file() }}<span>{{ _('View source') }}</span></a>
     {%- endif %}
   </div>
   {%- endif %}
diff --git a/sphinx_fuma/tests/test_llms.py b/sphinx_fuma/tests/test_llms.py
index ccc40f5..175423f 100644
--- a/sphinx_fuma/tests/test_llms.py
+++ b/sphinx_fuma/tests/test_llms.py
@@ -32,7 +32,7 @@ def test_llms_menu_links_to_generated_files(built_llms, page, region):
     assert 'aria-label="LLM documentation"' in menu.group(1)
     assert 'title="LLM documentation"' in menu.group(1)
     assert "fd-icon-bot" in menu.group(1)
-    links = re.findall(r'<a href="([^"]+)">([^<]+)</a>', menu.group(1))
+    links = re.findall(r'<a href="([^"]+)"[^>]*>([^<]+)</a>', menu.group(1))
     filenames = ["llms.txt", "llms-full.txt"] if full_build else ["llms.txt"]
     assert [label for _, label in links] == filenames
     for href, label in links:
diff --git a/sphinx_fuma/tests/test_theme.py b/sphinx_fuma/tests/test_theme.py
index aea931c..6232c1d 100644
--- a/sphinx_fuma/tests/test_theme.py
+++ b/sphinx_fuma/tests/test_theme.py
@@ -253,7 +253,7 @@ def test_standard_links_render_accessible_icons(self, built, region, closing_tag
 
     def test_unknown_navigation_link_retains_text(self, built):
         html = (built / "guide.html").read_text()
-        assert html.count('href="https://example.com/blog" target="_blank" rel="noopener">Blog</a>') == 2
+        assert html.count('href="https://example.com/blog" target="_blank" rel="noopener" title="Blog">Blog</a>') == 2
 
     def test_static_assets_are_copied(self, built):
         static = built / "_static"