refactor(api-style[toolbar]): Group badges and [source] in a toolbar container

why: Badges and [source] were separate flex items that could wrap
independently, causing [source] to land on a new line away from its
badges. The headerlink (¶) was also being pulled into the toolbar,
displacing it from its natural position next to the signature name.
what:
- Add gas-toolbar CSS class wrapping badges + [source] as a single flex item
- Toolbar uses flex-shrink: 0, margin-left: auto, order: 99 to stay
  right-aligned and always after the headerlink visually
- Stop manipulating headerlink nodes — Sphinx adds ¶ as raw HTML in
  depart_desc_signature, so it naturally appears after sig children
- Remove old per-element CSS order rules (replaced by toolbar grouping)
- Add test_inject_badges_headerlink_not_in_toolbar ensuring ¶ stays
  as a direct child of sig and never enters the toolbar
- Update existing tests for new toolbar node structure

Author: tony

packages/sphinx-autodoc-api-style/src/sphinx_autodoc_api_style/_css.py

@@ -32,6 +32,9 @@ class _CSS:
     >>> _CSS.BADGE_GROUP
     'gas-badge-group'
 
+    >>> _CSS.TOOLBAR
+    'gas-toolbar'
+
     >>> _CSS.obj_type("class")
     'gas-type-class'
     """
@@ -50,6 +53,8 @@ class _CSS:
     MOD_FINAL = f"{PREFIX}-mod-final"
     DEPRECATED = f"{PREFIX}-deprecated"
 
+    TOOLBAR = f"{PREFIX}-toolbar"
+
     @staticmethod
     def obj_type(name: str) -> str:
         """Return the type-specific CSS class, e.g. ``gas-type-function``.

packages/sphinx-autodoc-api-style/src/sphinx_autodoc_api_style/_static/css/api_style.css

@@ -191,26 +191,31 @@ body[data-theme="dark"] {
   --gas-deprecated-border: #c06060;
 }
 
-/* ── Badge group container ─────────────────────────────── */
+/* ── Signature flex layout ─────────────────────────────── */
 dl.py:not(.fixture) > dt {
   display: flex;
   align-items: center;
   gap: 0.35rem;
   flex-wrap: wrap;
 }
 
-dl.py:not(.fixture) > dt > .headerlink          { order: 1; }
-dl.py:not(.fixture) > dt > .gas-badge-group { order: 2; }
-dl.py:not(.fixture) > dt > a.reference.external { order: 3; }
-
-dl.py:not(.fixture) > dt .gas-badge-group {
+/* ── Toolbar: badges + [source] ────────────────────────── */
+dl.py:not(.fixture) > dt .gas-toolbar {
   display: inline-flex;
   align-items: center;
-  gap: 0.3rem;
+  gap: 0.35rem;
   flex-shrink: 0;
   margin-left: auto;
   white-space: nowrap;
   text-indent: 0;
+  order: 99;
+}
+
+dl.py:not(.fixture) > dt .gas-badge-group {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  white-space: nowrap;
 }
 
 /* ── Shared badge base ─────────────────────────────────── */

packages/sphinx-autodoc-api-style/src/sphinx_autodoc_api_style/_transforms.py

@@ -15,6 +15,7 @@
 from sphinx.writers.html5 import HTML5Translator
 
 from sphinx_autodoc_api_style._badges import build_badge_group
+from sphinx_autodoc_api_style._css import _CSS
 
 if t.TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -132,11 +133,11 @@ def _detect_deprecated(desc_node: addnodes.desc) -> bool:
 
 
 def _inject_badges(sig_node: addnodes.desc_signature, objtype: str) -> None:
-    """Inject badges and reorder signature children.
+    """Inject a toolbar containing badges, viewcode, and headerlink.
 
-    Appends a badge group to *sig_node* and reorders the headerlink and
-    viewcode link so the visual layout is:
-    ``name -> return -> headerlink -> badges (right-aligned) -> [source]``.
+    Builds a toolbar container (``gas-toolbar``) that groups the badge
+    group, ``[source]`` link, and permalink into a single flex item so
+    they stay together on the right side of the signature header.
 
     Guarded by ``gas_badges_injected`` flag.
 
@@ -168,25 +169,24 @@ def _inject_badges(sig_node: addnodes.desc_signature, objtype: str) -> None:
     badge_group = build_badge_group(objtype, modifiers=mods)
 
     viewcode_ref = None
-    headerlink_ref = None
     for child in list(sig_node.children):
-        if isinstance(child, nodes.reference):
-            if child.get("internal") is not True and any(
+        if (
+            isinstance(child, nodes.reference)
+            and child.get("internal") is not True
+            and any(
                 "viewcode-link" in getattr(gc, "get", lambda *_: "")("classes", [])
                 for gc in child.children
                 if isinstance(gc, nodes.inline)
-            ):
-                viewcode_ref = child
-                sig_node.remove(child)
-            elif "headerlink" in child.get("classes", []):
-                headerlink_ref = child
-                sig_node.remove(child)
-
-    if headerlink_ref is not None:
-        sig_node += headerlink_ref
-    sig_node += badge_group
+            )
+        ):
+            viewcode_ref = child
+            sig_node.remove(child)
+
+    toolbar = nodes.inline(classes=[_CSS.TOOLBAR])
+    toolbar += badge_group
     if viewcode_ref is not None:
-        sig_node += viewcode_ref
+        toolbar += viewcode_ref
+    sig_node += toolbar
 
 
 def on_doctree_resolved(

tests/ext/api_style/test_api_style.py

@@ -304,17 +304,20 @@ def test_inject_badges_idempotent() -> None:
     assert badge_count_1 == badge_count_2
 
 
-def test_inject_badges_adds_badge_group() -> None:
-    """Badge group is added to the signature."""
+def test_inject_badges_adds_toolbar_with_badge_group() -> None:
+    """Toolbar containing badge group is added to the signature."""
     sig = addnodes.desc_signature()
     sig += addnodes.desc_name("", "my_func")
     _inject_badges(sig, "function")
-    groups = [
+    toolbars = [
         c
         for c in sig.children
-        if isinstance(c, nodes.inline) and _CSS.BADGE_GROUP in c.get("classes", [])
+        if isinstance(c, nodes.inline) and _CSS.TOOLBAR in c.get("classes", [])
     ]
-    assert len(groups) == 1
+    assert len(toolbars) == 1
+    groups = list(toolbars[0].findall(nodes.inline))
+    badge_groups = [g for g in groups if _CSS.BADGE_GROUP in g.get("classes", [])]
+    assert len(badge_groups) == 1
 
 
 def test_inject_badges_detects_deprecated_parent() -> None:
@@ -336,8 +339,8 @@ def test_inject_badges_detects_deprecated_parent() -> None:
     assert "deprecated" in labels
 
 
-def test_inject_badges_reorders_viewcode() -> None:
-    """Viewcode [source] link is moved after badge group."""
+def test_inject_badges_toolbar_contains_viewcode() -> None:
+    """Viewcode [source] link is inside the toolbar, after badge group."""
     sig = addnodes.desc_signature()
     sig += addnodes.desc_name("", "my_func")
     viewcode_span = nodes.inline(classes=["viewcode-link"])
@@ -347,14 +350,66 @@ def test_inject_badges_reorders_viewcode() -> None:
 
     _inject_badges(sig, "function")
 
-    # Badge group should come before viewcode ref
-    children_classes: list[str] = []
-    for c in sig.children:
+    toolbars = [
+        c
+        for c in sig.children
+        if isinstance(c, nodes.inline) and _CSS.TOOLBAR in c.get("classes", [])
+    ]
+    assert len(toolbars) == 1
+    toolbar = toolbars[0]
+
+    toolbar_items: list[str] = []
+    for c in toolbar.children:
         if isinstance(c, nodes.inline) and _CSS.BADGE_GROUP in c.get("classes", []):
-            children_classes.append("badge_group")
-        elif isinstance(c, nodes.reference) and c.get("internal") is not True:
-            children_classes.append("viewcode")
-    assert children_classes.index("badge_group") < children_classes.index("viewcode")
+            toolbar_items.append("badge_group")
+        elif isinstance(c, nodes.reference):
+            toolbar_items.append("viewcode")
+    assert toolbar_items == ["badge_group", "viewcode"]
+
+
+def test_inject_badges_headerlink_not_in_toolbar() -> None:
+    """Headerlink stays as a direct child of sig, never inside the toolbar.
+
+    Sphinx's HTML writer adds the headerlink as raw HTML during
+    ``depart_desc_signature``, so it's not a doctree node during our
+    transform. But if a theme or extension adds one as a node, we must
+    leave it alone — it belongs next to the signature name, not grouped
+    with badges and [source] in the toolbar.
+    """
+    sig = addnodes.desc_signature()
+    sig += addnodes.desc_name("", "Server")
+
+    headerlink = nodes.reference(
+        "", "\u00b6", refuri="#libtmux.Server", classes=["headerlink"]
+    )
+    sig += headerlink
+
+    viewcode_span = nodes.inline(classes=["viewcode-link"])
+    viewcode_span += nodes.Text("[source]")
+    viewcode_ref = nodes.reference("", "", viewcode_span, internal=False)
+    sig += viewcode_ref
+
+    _inject_badges(sig, "class")
+
+    toolbar = None
+    for c in sig.children:
+        if isinstance(c, nodes.inline) and _CSS.TOOLBAR in c.get("classes", []):
+            toolbar = c
+            break
+    assert toolbar is not None
+
+    toolbar_refs = list(toolbar.findall(nodes.reference))
+    for ref in toolbar_refs:
+        assert "headerlink" not in ref.get("classes", []), (
+            "headerlink must not be inside the toolbar"
+        )
+
+    sig_direct_refs = [
+        c
+        for c in sig.children
+        if isinstance(c, nodes.reference) and "headerlink" in c.get("classes", [])
+    ]
+    assert len(sig_direct_refs) == 1, "headerlink should remain a direct child of sig"
 
 
 # ---------------------------------------------------------------------------