From 8d584ecccdbbc496de0075d9231aa8ae99eeaa51 Mon Sep 17 00:00:00 2001
From: Manas Srivastava <mastermanas805@gmail.com>
Date: Fri, 29 May 2026 14:03:26 +0530
Subject: [PATCH] fix(docs): add id + name + visually-hidden <label> to docs
 search input (a11y)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

UI-6 from the QA backlog (P3). The /docs sidebar search input shipped
with only an aria-label, failing the Lighthouse a11y rule "Form elements
must have labels". Password managers, form autofill, and screen readers
that prefer real <label htmlFor> over aria-label all degraded.

Fix:
  - Add id="docs-search" + name="docs-search" to the <input>.
  - Add a visually-hidden <label htmlFor="docs-search"> so the label
    is discoverable by AT and Lighthouse without affecting visual layout.
  - Keep the aria-label as a backstop (no harm, and a couple of older
    AT versions still prefer it).
  - Add a .visually-hidden CSS class — standard clip-rect pattern that
    removes the element from the layout but leaves it in the a11y tree.

Regression coverage in DocsPage.test.tsx:
  - input has id="docs-search" and name="docs-search"
  - a <label> with for="docs-search" exists in the DOM and resolves to
    the input

Verified: npm run gate green (1041 passed | 3 skipped).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/pages/DocsPage.test.tsx | 21 +++++++++++++++++++++
 src/pages/DocsPage.tsx      | 28 ++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/src/pages/DocsPage.test.tsx b/src/pages/DocsPage.test.tsx
index 83bc32d..011554f 100644
--- a/src/pages/DocsPage.test.tsx
+++ b/src/pages/DocsPage.test.tsx
@@ -88,3 +88,24 @@ describe('DocsPage', () => {
     expect(document.activeElement).not.toBe(input)
   })
 })
+
+// UI-6 (2026-05-29): the docs search input shipped with only an aria-label,
+// failing the a11y rule "Form elements must have labels" — password managers,
+// form autofill, and Lighthouse a11y all expect a real <label htmlFor> + a
+// matching id/name on the input. This block pins the wiring.
+describe('DocsPage — search input a11y (UI-6)', () => {
+  it('input has an id and a name (so a <label htmlFor> can resolve and form autofill works)', () => {
+    renderPage()
+    const input = screen.getByLabelText('Search documentation') as HTMLInputElement
+    expect(input.id).toBe('docs-search')
+    expect(input.name).toBe('docs-search')
+  })
+
+  it('a real <label htmlFor> exists and its for attribute matches the input id', () => {
+    renderPage()
+    const input = screen.getByLabelText('Search documentation') as HTMLInputElement
+    const label = document.querySelector(`label[for="${input.id}"]`)
+    expect(label).not.toBeNull()
+    expect((label as HTMLLabelElement).htmlFor).toBe(input.id)
+  })
+})
diff --git a/src/pages/DocsPage.tsx b/src/pages/DocsPage.tsx
index 746205b..f60cd8f 100644
--- a/src/pages/DocsPage.tsx
+++ b/src/pages/DocsPage.tsx
@@ -159,8 +159,19 @@ function DocsBody() {
         <p className="docs-toc-label">Docs</p>
 
         <div className="docs-search">
+          {/* UI-6 (2026-05-29): visually-hidden <label> + matching id/name
+              on the input so password managers, form autofill, and screen
+              readers all resolve a real label, not just an aria-label.
+              The .visually-hidden CSS class is defined in the styles block
+              below — keeps the label out of the visual layout while
+              leaving it discoverable by AT and Lighthouse's a11y audit. */}
+          <label htmlFor="docs-search" className="visually-hidden">
+            Search documentation
+          </label>
           <input
             ref={inputRef}
+            id="docs-search"
+            name="docs-search"
             type="search"
             value={query}
             onChange={(e) => setQuery(e.target.value)}
@@ -274,6 +285,23 @@ function DocsStyles() {
         position: relative;
         margin: 0 0 16px;
       }
+      /* UI-6 (2026-05-29): visually-hidden — standard a11y pattern. Keeps
+         the search-field <label> out of the visual layout while leaving
+         it discoverable by screen readers, form autofill, and Lighthouse's
+         a11y audit. (aria-label alone failed the a11y rule "Form elements
+         must have labels"; password managers and Lighthouse both still
+         expect a real <label htmlFor>.) */
+      .visually-hidden {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+      }
       .docs-search-input {
         width: 100%;
         padding: 7px 28px 7px 10px;