refactor: voice input cleanup and user education

ammar-agent · ammar-agent · commit 4d9552d428cf · 2025-12-01T23:51:10.000-06:00
User education:
- Show mic button even without OpenAI key (disabled with tooltip)
- Tooltip explains: 'Configure in Settings → Providers'
- Toast error when trying to use keybind/command without key

DRY improvements:
- Extract WaveformBars component for reusable animated bars
- Remove unused Web Speech API error message mappings

Code quality:
- Add isApiKeySet to hook result for explicit checking
- shouldShowUI now only checks platform support, not API key
- Verified no race conditions in hook logic
diff --git a/src/browser/components/ChatInput/VoiceInputButton.tsx b/src/browser/components/ChatInput/VoiceInputButton.tsx
@@ -6,7 +6,8 @@
  * - Idle: Subtle gray mic icon
  * - Recording: Blue pulsing mic
  * - Transcribing: Amber spinning loader
- * - Hidden: When on mobile, unsupported, or no OpenAI key
+ * - Disabled (no API key): Subtle gray with explanatory tooltip
+ * - Hidden: When on mobile or unsupported
  */
 
 import React from "react";
@@ -19,22 +20,26 @@ interface VoiceInputButtonProps {
   isListening: boolean;
   isTranscribing: boolean;
   isSupported: boolean;
+  isApiKeySet: boolean;
   shouldShowUI: boolean;
   onToggle: () => void;
   disabled?: boolean;
 }
 
 export const VoiceInputButton: React.FC<VoiceInputButtonProps> = (props) => {
-  // Don't render if we shouldn't show UI (mobile, unsupported, or no OpenAI key)
+  // Don't render on mobile or unsupported platforms
   if (!props.shouldShowUI) {
     return null;
   }
 
-  const label = props.isTranscribing
-    ? "Transcribing..."
-    : props.isListening
-      ? "Stop recording"
-      : "Voice input";
+  const needsApiKey = !props.isApiKeySet;
+  const label = needsApiKey
+    ? "Voice input (requires OpenAI API key)"
+    : props.isTranscribing
+      ? "Transcribing..."
+      : props.isListening
+        ? "Stop recording"
+        : "Voice input";
 
   const Icon = props.isTranscribing ? Loader2 : Mic;
 
@@ -43,7 +48,9 @@ export const VoiceInputButton: React.FC<VoiceInputButtonProps> = (props) => {
       <button
         type="button"
         onClick={props.onToggle}
-        disabled={(props.disabled ?? false) || !props.isSupported || props.isTranscribing}
+        disabled={
+          (props.disabled ?? false) || !props.isSupported || props.isTranscribing || needsApiKey
+        }
         aria-label={label}
         aria-pressed={props.isListening}
         className={cn(
@@ -59,7 +66,17 @@ export const VoiceInputButton: React.FC<VoiceInputButtonProps> = (props) => {
         <Icon className={cn("h-4 w-4", props.isTranscribing && "animate-spin")} strokeWidth={1.5} />
       </button>
       <Tooltip className="tooltip" align="right">
-        {label} ({formatKeybind(KEYBINDS.TOGGLE_VOICE_INPUT)})
+        {needsApiKey ? (
+          <>
+            Voice input requires OpenAI API key.
+            <br />
+            Configure in Settings → Providers.
+          </>
+        ) : (
+          <>
+            {label} ({formatKeybind(KEYBINDS.TOGGLE_VOICE_INPUT)})
+          </>
+        )}
       </Tooltip>
     </TooltipWrapper>
   );
diff --git a/src/browser/components/ChatInput/WaveformBars.tsx b/src/browser/components/ChatInput/WaveformBars.tsx
@@ -0,0 +1,32 @@
+/**
+ * Animated waveform bars for voice recording UI.
+ * Shows 5 bars with staggered pulse animation.
+ */
+
+import { cn } from "@/common/lib/utils";
+
+interface WaveformBarsProps {
+  /** Color class for the bars (e.g., "bg-blue-500") */
+  colorClass: string;
+  /** Whether to mirror the animation (for right-side waveform) */
+  mirrored?: boolean;
+}
+
+export const WaveformBars: React.FC<WaveformBarsProps> = (props) => {
+  const indices = props.mirrored ? [4, 3, 2, 1, 0] : [0, 1, 2, 3, 4];
+
+  return (
+    <div className="flex items-center gap-1">
+      {indices.map((i, displayIndex) => (
+        <div
+          key={displayIndex}
+          className={cn("w-1 rounded-full", props.colorClass)}
+          style={{
+            height: `${12 + Math.sin(i * 0.8) * 8}px`,
+            animation: `pulse 0.8s ease-in-out ${i * 0.1}s infinite alternate`,
+          }}
+        />
+      ))}
+    </div>
+  );
+};
diff --git a/src/browser/components/ChatInput/index.tsx b/src/browser/components/ChatInput/index.tsx
@@ -67,6 +67,7 @@ import { useCreationWorkspace } from "./useCreationWorkspace";
 import { useTutorial } from "@/browser/contexts/TutorialContext";
 import { useVoiceInput } from "@/browser/hooks/useVoiceInput";
 import { VoiceInputButton } from "./VoiceInputButton";
+import { WaveformBars } from "./WaveformBars";
 
 const LEADING_COMMAND_NOISE = /^(?:\s|\u200B|\u200C|\u200D|\u200E|\u200F|\uFEFF)+/;
 
@@ -173,17 +174,10 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
 
   const handleVoiceError = useCallback(
     (error: string) => {
-      // Map common errors to user-friendly messages
-      const errorMessages: Record<string, string> = {
-        "not-allowed": "Microphone access denied. Please allow microphone access and try again.",
-        "no-speech": "No speech detected. Please try again.",
-        network: "Network error. Please check your connection.",
-        "audio-capture": "No microphone found. Please connect a microphone.",
-      };
       setToast({
         id: Date.now().toString(),
         type: "error",
-        message: errorMessages[error] ?? `Voice input error: ${error}`,
+        message: error,
       });
     },
     [setToast]
@@ -506,12 +500,20 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
     if (!voiceInput.shouldShowUI) return;
 
     const handler = () => {
+      if (!voiceInput.isApiKeySet) {
+        setToast({
+          id: Date.now().toString(),
+          type: "error",
+          message: "Voice input requires OpenAI API key. Configure in Settings → Providers.",
+        });
+        return;
+      }
       voiceInput.toggleListening();
     };
     window.addEventListener(CUSTOM_EVENTS.TOGGLE_VOICE_INPUT, handler as EventListener);
     return () =>
       window.removeEventListener(CUSTOM_EVENTS.TOGGLE_VOICE_INPUT, handler as EventListener);
-  }, [voiceInput]);
+  }, [voiceInput, setToast]);
 
   // Auto-focus chat input when workspace changes (workspace only)
   const workspaceIdForFocus = variant === "workspace" ? props.workspaceId : null;
@@ -847,6 +849,14 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
     // Handle voice input toggle (Ctrl+D / Cmd+D)
     if (matchesKeybind(e, KEYBINDS.TOGGLE_VOICE_INPUT) && voiceInput.shouldShowUI) {
       e.preventDefault();
+      if (!voiceInput.isApiKeySet) {
+        setToast({
+          id: Date.now().toString(),
+          type: "error",
+          message: "Voice input requires OpenAI API key. Configure in Settings → Providers.",
+        });
+        return;
+      }
       voiceInput.toggleListening();
       return;
     }
@@ -1002,22 +1012,9 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
                 )}
                 aria-label={voiceInput.isListening ? "Stop recording" : "Transcribing..."}
               >
-                {/* Animated waveform bars */}
-                <div className="flex items-center gap-1">
-                  {[0, 1, 2, 3, 4].map((i) => (
-                    <div
-                      key={i}
-                      className={cn(
-                        "w-1 rounded-full",
-                        voiceInput.isListening ? "bg-blue-500" : "bg-amber-500"
-                      )}
-                      style={{
-                        height: `${12 + Math.sin(i * 0.8) * 8}px`,
-                        animation: `pulse 0.8s ease-in-out ${i * 0.1}s infinite alternate`,
-                      }}
-                    />
-                  ))}
-                </div>
+                <WaveformBars
+                  colorClass={voiceInput.isListening ? "bg-blue-500" : "bg-amber-500"}
+                />
                 <span
                   className={cn(
                     "text-sm font-medium",
@@ -1028,21 +1025,10 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
                     ? `Recording... space to send, ${formatKeybind(KEYBINDS.TOGGLE_VOICE_INPUT)} to stop`
                     : "Transcribing..."}
                 </span>
-                <div className="flex items-center gap-1">
-                  {[0, 1, 2, 3, 4].map((i) => (
-                    <div
-                      key={i}
-                      className={cn(
-                        "w-1 rounded-full",
-                        voiceInput.isListening ? "bg-blue-500" : "bg-amber-500"
-                      )}
-                      style={{
-                        height: `${12 + Math.sin((4 - i) * 0.8) * 8}px`,
-                        animation: `pulse 0.8s ease-in-out ${(4 - i) * 0.1}s infinite alternate`,
-                      }}
-                    />
-                  ))}
-                </div>
+                <WaveformBars
+                  colorClass={voiceInput.isListening ? "bg-blue-500" : "bg-amber-500"}
+                  mirrored
+                />
               </button>
             ) : (
               <>
@@ -1074,6 +1060,7 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
                     isListening={voiceInput.isListening}
                     isTranscribing={voiceInput.isTranscribing}
                     isSupported={voiceInput.isSupported}
+                    isApiKeySet={voiceInput.isApiKeySet}
                     shouldShowUI={voiceInput.shouldShowUI}
                     onToggle={voiceInput.toggleListening}
                     disabled={disabled || isSending}
diff --git a/src/browser/hooks/useVoiceInput.ts b/src/browser/hooks/useVoiceInput.ts
@@ -42,7 +42,9 @@ export interface UseVoiceInputResult {
   isTranscribing: boolean;
   /** Whether the browser supports MediaRecorder */
   isSupported: boolean;
-  /** Whether we should show voice UI (supported, not mobile, API key set) */
+  /** Whether OpenAI API key is configured */
+  isApiKeySet: boolean;
+  /** Whether we should show voice UI (supported and not mobile) */
   shouldShowUI: boolean;
   /** Start recording for voice input */
   startListening: () => void;
@@ -205,7 +207,9 @@ export function useVoiceInput(options: UseVoiceInputOptions): UseVoiceInputResul
     isListening,
     isTranscribing,
     isSupported,
-    shouldShowUI: isSupported && !isMobile && openAIKeySet,
+    isApiKeySet: openAIKeySet,
+    // Show UI on supported desktop platforms (mobile has native dictation)
+    shouldShowUI: isSupported && !isMobile,
     startListening: () => void startListening(),
     stopListening,
     stopListeningAndSend,
