From 36f136bcda065780d7a1560df7442308238fd8c4 Mon Sep 17 00:00:00 2001
From: Patrick Schmitt <45056826+patschmittdev@users.noreply.github.com>
Date: Sun, 13 Sep 2026 11:03:21 -0400
Subject: [PATCH] fix(site): repair mobile docs menu

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .../src/components/AccessibleMenuToggle.astro | 122 ++++++++++++++----
 site/tests/visual.spec.ts                     |  21 ++-
 2 files changed, 115 insertions(+), 28 deletions(-)

diff --git a/site/src/components/AccessibleMenuToggle.astro b/site/src/components/AccessibleMenuToggle.astro
index 0aa33c2..91a5dcb 100644
--- a/site/src/components/AccessibleMenuToggle.astro
+++ b/site/src/components/AccessibleMenuToggle.astro
@@ -1,36 +1,114 @@
----
-import DefaultMobileMenuToggle from '@astrojs/starlight/components/MobileMenuToggle.astro';
----
-
-<ziggurat-menu-state><DefaultMobileMenuToggle /></ziggurat-menu-state>
+<starlight-menu-button class="print:hidden">
+  <button
+    aria-expanded="false"
+    aria-label={Astro.locals.t('menuButton.accessibleLabel')}
+    aria-controls="starlight__sidebar"
+    class="sl-flex md:sl-hidden"
+  >
+    <svg aria-hidden="true" class="open-menu" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M3 8h18a1 1 0 1 0 0-2H3a1 1 0 0 0 0 2Zm18 8H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Zm0-5H3a1 1 0 0 0 0 2h18a1 1 0 0 0 0-2Z"></path>
+    </svg>
+    <svg aria-hidden="true" class="close-menu" viewBox="0 0 24 24" fill="currentColor">
+      <path d="m13.41 12 6.3-6.29a1.004 1.004 0 1 0-1.42-1.42L12 10.59l-6.29-6.3a1.004 1.004 0 0 0-1.42 1.42l6.3 6.29-6.3 6.29a1 1 0 0 0 0 1.42.998.998 0 0 0 1.42 0l6.29-6.3 6.29 6.3a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.42L13.41 12Z"></path>
+    </svg>
+  </button>
+</starlight-menu-button>
 
 <script>
-  class MenuState extends HTMLElement {
-    observer: MutationObserver | undefined;
+  class AccessibleMenuButton extends HTMLElement {
+    button = this.querySelector('button');
+
+    constructor() {
+      super();
+      if (!this.button) throw new Error('Documentation menu toggle markup is missing.');
+
+      this.button.addEventListener('click', () => this.toggleExpanded());
+      this.closest('nav')?.addEventListener('keyup', (event) => this.closeOnEscape(event));
+      matchMedia('(min-width: 50em)').addEventListener('change', () => this.setExpanded(false));
+    }
 
-    connectedCallback() {
-      const toggle = this.querySelector('starlight-menu-button');
-      const button = toggle?.querySelector('button');
-      if (!toggle || !button) throw new Error('Documentation menu toggle markup is missing.');
+    setExpanded(expanded: boolean) {
+      const value = String(expanded);
+      this.setAttribute('aria-expanded', value);
+      this.button?.setAttribute('aria-expanded', value);
+      document.body.toggleAttribute('data-mobile-menu-expanded', expanded);
+      document.querySelectorAll<HTMLElement>('.main-frame, .sl-skip-link').forEach((element) => {
+        element.toggleAttribute('inert', expanded);
+      });
+    }
 
-      // The framework updates its host state; expose the same state on its button.
-      const sync = () => button.setAttribute('aria-expanded',
-        String(toggle.getAttribute('aria-expanded') === 'true'));
-      this.observer = new MutationObserver(sync);
-      this.observer.observe(toggle, { attributes: true, attributeFilter: ['aria-expanded'] });
-      sync();
+    toggleExpanded() {
+      this.setExpanded(this.getAttribute('aria-expanded') !== 'true');
     }
 
-    disconnectedCallback() {
-      this.observer?.disconnect();
+    closeOnEscape(event: KeyboardEvent) {
+      if (event.code !== 'Escape') return;
+      this.setExpanded(false);
+      this.button?.focus();
     }
   }
 
-  customElements.define('ziggurat-menu-state', MenuState);
+  customElements.define('starlight-menu-button', AccessibleMenuButton);
 </script>
 
 <style>
-  ziggurat-menu-state {
-    display: contents;
+  @layer starlight.core {
+    button {
+      position: fixed;
+      top: calc((var(--sl-nav-height) - var(--sl-menu-button-size)) / 2);
+      inset-inline-end: var(--sl-nav-pad-x);
+      z-index: var(--sl-z-index-navbar);
+      align-items: center;
+      justify-content: center;
+      border: 0;
+      border-radius: 0;
+      width: var(--sl-menu-button-size);
+      height: var(--sl-menu-button-size);
+      padding: 0.5rem;
+      background-color: var(--sl-color-white);
+      color: var(--sl-color-black);
+      box-shadow: none;
+      cursor: pointer;
+    }
+
+    button svg {
+      width: 1rem;
+      height: 1rem;
+    }
+
+    [aria-expanded='true'] button {
+      background-color: var(--sl-color-gray-2);
+    }
+
+    [aria-expanded='true'] button .open-menu {
+      display: none;
+    }
+
+    :not([aria-expanded='true']) button .close-menu {
+      display: none;
+    }
+
+    :global([data-theme='light']) button {
+      background-color: var(--sl-color-black);
+      color: var(--sl-color-white);
+    }
+
+    :global([data-theme='light']) [aria-expanded='true'] button {
+      background-color: var(--sl-color-gray-5);
+    }
+  }
+</style>
+
+<style is:global>
+  @layer starlight.core {
+    [data-mobile-menu-expanded] {
+      overflow: hidden;
+    }
+
+    @media (min-width: 50rem) {
+      [data-mobile-menu-expanded] {
+        overflow: auto;
+      }
+    }
   }
 </style>
diff --git a/site/tests/visual.spec.ts b/site/tests/visual.spec.ts
index 62a7e30..37af4d8 100644
--- a/site/tests/visual.spec.ts
+++ b/site/tests/visual.spec.ts
@@ -152,16 +152,25 @@ for (const route of routes) {
 
       const menu = page.getByRole('button', { name: 'Menu', exact: true });
       if (await menu.isVisible()) {
-        await menu.focus();
-        await page.keyboard.press('Enter');
+        const closedIcon = page.locator('starlight-menu-button .open-menu');
+        const buttonBox = await menu.boundingBox();
+        const iconBox = await closedIcon.boundingBox();
+        expect(buttonBox).not.toBeNull();
+        expect(iconBox).not.toBeNull();
+        expect(Math.abs((buttonBox!.x + buttonBox!.width / 2) - (iconBox!.x + iconBox!.width / 2)))
+          .toBeLessThanOrEqual(1);
+        expect(Math.abs((buttonBox!.y + buttonBox!.height / 2) - (iconBox!.y + iconBox!.height / 2)))
+          .toBeLessThanOrEqual(1);
+
+        await menu.click();
         await expect(menu).toHaveAttribute('aria-expanded', 'true');
         await expect(page.locator('body')).toHaveAttribute('data-mobile-menu-expanded', '');
-        await page.keyboard.press('Enter');
+        await expect(page.locator('#starlight__sidebar')).toBeVisible();
+        await menu.click();
         await expect(menu).toHaveAttribute('aria-expanded', 'false');
         await expect(page.locator('body')).not.toHaveAttribute('data-mobile-menu-expanded', '');
-        const box = await menu.boundingBox();
-        expect(box?.width).toBeGreaterThanOrEqual(44);
-        expect(box?.height).toBeGreaterThanOrEqual(44);
+        expect(buttonBox?.width).toBeGreaterThanOrEqual(44);
+        expect(buttonBox?.height).toBeGreaterThanOrEqual(44);
       }
     }