Add voice support to search bar on supported browsers

Author: webstackdev

package-lock.json

@@ -100,6 +100,7 @@
     "@types/confusing-browser-globals": "1.0.3",
     "@types/cross-spawn": "6.0.6",
     "@types/dedent": "^0.7.2",
+    "@types/dom-speech-recognition": "^0.0.7",
     "@types/eslint": "^9.6.1",
     "@types/eslint-plugin-security": "3.0.0",
     "@types/glidejs__glide": "^3.6.6",

package.json

@@ -34,9 +34,31 @@ const flushMicrotasks = async () => {
 describe('SearchBar web component', () => {
   let container: AstroContainer
 
+  class MockSpeechRecognition {
+    public continuous = false
+    public interimResults = false
+    public lang = 'en-US'
+
+    public onstart: (() => void) | null = null
+    public onend: (() => void) | null = null
+    public onerror: ((event: { error: string }) => void) | null = null
+    public onresult: ((event: unknown) => void) | null = null
+
+    public start = vi.fn(() => {
+      this.onstart?.()
+    })
+
+    public stop = vi.fn(() => {
+      this.onend?.()
+    })
+  }
+
   beforeEach(async () => {
     container = await AstroContainer.create()
     searchQueryMock.mockReset()
+
+    delete (globalThis as unknown as Record<string, unknown>).SpeechRecognition
+    delete (globalThis as unknown as Record<string, unknown>).webkitSpeechRecognition
   })
 
   const runComponentRender = async (
@@ -166,8 +188,10 @@ describe('SearchBar web component', () => {
       const toggleBtn = element.querySelector('[data-search-toggle]') as HTMLButtonElement
       const input = element.querySelector('[data-search-input]') as HTMLInputElement
       const clearBtn = element.querySelector('[data-search-clear]') as HTMLButtonElement
+      const micBtn = element.querySelector('[data-search-mic]') as HTMLButtonElement
 
       expect(clearBtn.hasAttribute('hidden')).toBe(true)
+      expect(micBtn.hasAttribute('hidden')).toBe(true)
 
       toggleBtn.click()
       await flushMicrotasks()
@@ -177,6 +201,8 @@ describe('SearchBar web component', () => {
       await flushMicrotasks()
 
       expect(clearBtn.hasAttribute('hidden')).toBe(false)
+      // Mic stays hidden unless the browser supports speech recognition.
+      expect(micBtn.hasAttribute('hidden')).toBe(true)
 
       clearBtn.click()
       await flushMicrotasks()
@@ -186,4 +212,34 @@ describe('SearchBar web component', () => {
       expect(clearBtn.hasAttribute('hidden')).toBe(false)
     })
   })
+
+  it('fills the query from speech recognition when available', async () => {
+    await runHeaderComponentRender(async ({ element, window }) => {
+      ;(window as unknown as { SpeechRecognition?: unknown }).SpeechRecognition = MockSpeechRecognition as unknown
+      ;(window as unknown as { webkitSpeechRecognition?: unknown }).webkitSpeechRecognition =
+        MockSpeechRecognition as unknown
+
+      const toggleBtn = element.querySelector('[data-search-toggle]') as HTMLButtonElement
+      const input = element.querySelector('[data-search-input]') as HTMLInputElement
+      const micBtn = element.querySelector('[data-search-mic]') as HTMLButtonElement
+
+      toggleBtn.click()
+      await flushMicrotasks()
+
+      micBtn.click()
+      await flushMicrotasks()
+
+      // Simulate a recognition result.
+      const recognition = (element as unknown as { speechRecognition?: MockSpeechRecognition }).speechRecognition
+      expect(recognition).toBeTruthy()
+
+      recognition?.onresult?.({
+        resultIndex: 0,
+        results: [[{ transcript: 'hello world' }]],
+      } as unknown)
+
+      await flushMicrotasks()
+      expect(input.value).toBe('hello world')
+    })
+  })
 })

src/components/Search/SearchBar/client/__tests__/index.spec.ts

@@ -24,9 +24,13 @@ export class SearchBarElement extends LitElement {
 
   private toggleBtn: HTMLButtonElement | null = null
   private panel: HTMLElement | null = null
+  private micBtn: HTMLButtonElement | null = null
   private clearBtn: HTMLButtonElement | null = null
   private isExpanded = true
 
+  private speechRecognition: SpeechRecognition | null = null
+  private isListening = false
+
   private isOutsideListenersAttached = false
   private unsubscribeHeaderSearchExpanded: (() => void) | null = null
 
@@ -62,7 +66,7 @@ export class SearchBarElement extends LitElement {
 
   private cacheElements(): void {
     const { form, input, resultsContainer, resultsList } = getSearchBarElements(this)
-    const { toggleBtn, panel, clearBtn } = getSearchBarOptionalElements(this)
+    const { toggleBtn, panel, micBtn, clearBtn } = getSearchBarOptionalElements(this)
 
     this.form = form
     this.input = input
@@ -71,10 +75,12 @@ export class SearchBarElement extends LitElement {
 
     this.toggleBtn = toggleBtn
     this.panel = panel
+    this.micBtn = micBtn
     this.clearBtn = clearBtn
     this.isExpanded = this.toggleBtn ? getHeaderSearchExpanded() : this.getIsExpandedFromDom()
 
     this.updateClearButtonVisibility()
+    this.updateMicButtonVisibility()
   }
 
   private initHeaderExpandedState(): void {
@@ -153,6 +159,11 @@ export class SearchBarElement extends LitElement {
       this.clearBtn.dataset['searchListener'] = 'true'
     }
 
+    if (this.micBtn && !this.micBtn.dataset['searchListener']) {
+      this.micBtn.addEventListener('click', this.handleMicClick)
+      this.micBtn.dataset['searchListener'] = 'true'
+    }
+
     if (!this.dataset['searchKeyListener']) {
       this.addEventListener('keydown', this.handleKeyDown)
       this.dataset['searchKeyListener'] = 'true'
@@ -189,6 +200,7 @@ export class SearchBarElement extends LitElement {
     }
 
     if (!isExpanded) {
+      this.stopSpeechRecognition()
       this.clearResults()
       this.hideResults()
       this.detachOutsideListeners()
@@ -197,6 +209,7 @@ export class SearchBarElement extends LitElement {
     }
 
     this.updateClearButtonVisibility()
+    this.updateMicButtonVisibility()
   }
 
   private updateClearButtonVisibility(): void {
@@ -210,6 +223,141 @@ export class SearchBarElement extends LitElement {
     this.clearBtn.setAttribute('aria-label', query.length > 0 ? 'Clear search' : 'Close search')
   }
 
+  private getSpeechRecognitionCtor(): (new () => SpeechRecognition) | null {
+    const view = (this.ownerDocument?.defaultView ?? null) as
+      | {
+          SpeechRecognition?: new () => SpeechRecognition
+          webkitSpeechRecognition?: new () => SpeechRecognition
+        }
+      | null
+
+    const globalAny = globalThis as unknown as {
+      SpeechRecognition?: new () => SpeechRecognition
+      webkitSpeechRecognition?: new () => SpeechRecognition
+      window?: {
+        SpeechRecognition?: new () => SpeechRecognition
+        webkitSpeechRecognition?: new () => SpeechRecognition
+      }
+    }
+
+    return (
+      view?.SpeechRecognition ??
+      view?.webkitSpeechRecognition ??
+      globalAny.SpeechRecognition ??
+      globalAny.webkitSpeechRecognition ??
+      globalAny.window?.SpeechRecognition ??
+      globalAny.window?.webkitSpeechRecognition ??
+      null
+    )
+  }
+
+  private updateMicButtonVisibility(): void {
+    if (!this.micBtn) {
+      return
+    }
+
+    const supported = this.getSpeechRecognitionCtor() !== null
+    const shouldShow = supported && this.isExpanded
+    this.micBtn.toggleAttribute('hidden', !shouldShow)
+    this.micBtn.setAttribute('aria-label', this.isListening ? 'Stop voice search' : 'Voice search')
+  }
+
+  private ensureSpeechRecognition(): SpeechRecognition | null {
+    if (this.speechRecognition) {
+      return this.speechRecognition
+    }
+
+    const ctor = this.getSpeechRecognitionCtor()
+    if (!ctor) {
+      return null
+    }
+
+    // Lazily create recognition; keeps SSR/older browsers safe.
+    const recognition = new ctor()
+    recognition.continuous = false
+    recognition.interimResults = true
+
+    const docLang = document.documentElement.getAttribute('lang')
+    recognition.lang = docLang && docLang.length > 0 ? docLang : 'en-US'
+
+    recognition.onstart = () => {
+      this.isListening = true
+      this.updateMicButtonVisibility()
+    }
+
+    recognition.onend = () => {
+      this.isListening = false
+      this.updateMicButtonVisibility()
+    }
+
+    recognition.onerror = (event: SpeechRecognitionErrorEvent) => {
+      const context = { scriptName: 'SearchBarElement', operation: 'speechRecognition.onerror' }
+      handleScriptError(new Error(`Speech recognition error: ${event.error}`), context)
+      this.stopSpeechRecognition()
+    }
+
+    recognition.onresult = (event: SpeechRecognitionEvent) => {
+      if (!this.input) {
+        return
+      }
+
+      const transcript = this.getTranscriptFromSpeechEvent(event)
+      if (!transcript) {
+        return
+      }
+
+      this.input.value = transcript
+      this.input.dispatchEvent(new Event('input', { bubbles: true }))
+      this.input.focus()
+    }
+
+    this.speechRecognition = recognition
+    return recognition
+  }
+
+  private getTranscriptFromSpeechEvent(event: SpeechRecognitionEvent): string {
+    // Note: Safari exposes only `webkitSpeechRecognition` and can behave differently.
+    // We keep the extraction defensive so it works across implementations and in tests.
+    const eventAny = event as unknown as {
+      resultIndex?: number
+      results?: ArrayLike<ArrayLike<{ transcript?: string } & { confidence?: number }> & { isFinal?: boolean }>
+    }
+
+    const resultIndex = eventAny.resultIndex ?? 0
+    const result = eventAny.results?.[resultIndex]
+    const firstAlternative = result?.[0]
+    return (firstAlternative?.transcript ?? '').trim()
+  }
+
+  private startSpeechRecognition(): void {
+    const recognition = this.ensureSpeechRecognition()
+    if (!recognition) {
+      this.updateMicButtonVisibility()
+      return
+    }
+
+    try {
+      recognition.start()
+    } catch (error) {
+      // Some implementations throw if start() is called while already active.
+      handleScriptError(error, { scriptName: 'SearchBarElement', operation: 'speechRecognition.start' })
+    }
+  }
+
+  private stopSpeechRecognition(): void {
+    if (!this.speechRecognition) {
+      this.isListening = false
+      this.updateMicButtonVisibility()
+      return
+    }
+
+    try {
+      this.speechRecognition.stop()
+    } catch (error) {
+      handleScriptError(error, { scriptName: 'SearchBarElement', operation: 'speechRecognition.stop' })
+    }
+  }
+
   private expand(): void {
     if (!this.toggleBtn) {
       return
@@ -403,6 +551,23 @@ export class SearchBarElement extends LitElement {
     this.input.focus()
   }
 
+  private readonly handleMicClick = () => {
+    if (!this.input) {
+      return
+    }
+
+    if (!this.isExpanded) {
+      this.expand()
+    }
+
+    if (this.isListening) {
+      this.stopSpeechRecognition()
+      return
+    }
+
+    this.startSpeechRecognition()
+  }
+
   private showResults(): void {
     this.resultsContainer?.classList.remove('hidden')
   }

src/components/Search/SearchBar/client/index.ts

@@ -11,6 +11,7 @@ export const SELECTORS = {
 export const OPTIONAL_SELECTORS = {
   toggleBtn: '[data-search-toggle]',
   panel: '[data-search-panel]',
+  micBtn: '[data-search-mic]',
   clearBtn: '[data-search-clear]',
 } as const
 
@@ -65,11 +66,13 @@ export function getSearchBarElements(context: Element) {
 export function getSearchBarOptionalElements(context: Element) {
   const toggleBtn = context.querySelector(OPTIONAL_SELECTORS.toggleBtn)
   const panel = context.querySelector(OPTIONAL_SELECTORS.panel)
+  const micBtn = context.querySelector(OPTIONAL_SELECTORS.micBtn)
   const clearBtn = context.querySelector(OPTIONAL_SELECTORS.clearBtn)
 
   return {
     toggleBtn: toggleBtn instanceof HTMLButtonElement ? toggleBtn : null,
     panel: panel instanceof HTMLElement ? panel : null,
+    micBtn: micBtn instanceof HTMLButtonElement ? micBtn : null,
     clearBtn: clearBtn instanceof HTMLButtonElement ? clearBtn : null,
   }
 }

src/components/Search/SearchBar/client/selectors.ts

@@ -1,6 +1,7 @@
 ---
 import Icon from '@components/Icon/index.astro'
 import closeSvg from '../../../icons/close.svg?raw'
+import microphoneSvg from '../../../icons/microphone.svg?raw'
 import styles from './index.module.css'
 
 export interface Props {
@@ -56,6 +57,16 @@ const clearButtonLabel = hasInitialQuery ? 'Clear search' : 'Close search'
             ]}
           />
 
+          <button
+            data-search-mic
+            type="button"
+            aria-label="Voice search"
+            hidden
+            class="relative inline-flex items-center justify-center w-(--header-icon-size) h-(--header-icon-size) shrink-0 rounded-full border-0 bg-transparent text-content-active hover:text-primary focus:outline-none focus-visible:text-primary transition-colors duration-150 ease-linear"
+          >
+            <span aria-hidden="true" set:html={microphoneSvg} />
+          </button>
+
           <button
             data-search-clear
             type="button"