Skip to content

a11y: screen reader and keyboard improvements #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jamiepine merged 3 commits into from
Mar 13, 2026
+327 −23
Merged

a11y: screen reader and keyboard improvements #243

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19a28bf
a11y: screen reader and keyboard improvements
ways2read Mar 7, 2026
9955e1d
a11y: address PR feedback and polish docs
ways2read Mar 7, 2026
b92b0dd
merge: resolve conflicts with latest main
jamiepine Mar 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 20 additions & 2 deletions app/src/components/AudioPlayer/AudioPlayer.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { useQuery } from '@tanstack/react-query';
import { Pause, Play, Repeat, Volume2, VolumeX, X } from 'lucide-react';
import { useEffect, useMemo, useRef, useState } from 'react';
import { useEffect, useId, useMemo, useRef, useState } from 'react';
import WaveSurfer from 'wavesurfer.js';
import { Button } from '@/components/ui/button';
import { Slider } from '@/components/ui/slider';
Expand All @@ -12,6 +12,7 @@ import { usePlatform } from '@/platform/PlatformContext';

export function AudioPlayer() {
const platform = usePlatform();
const volumeLabelId = useId();
const {
audioUrl,
audioId,
Expand Down Expand Up @@ -831,6 +832,13 @@ export function AudioPlayer() {
disabled={isLoading || duration === 0}
className="shrink-0"
title={duration === 0 && !isLoading ? 'Audio not loaded' : ''}
aria-label={
duration === 0 && !isLoading
? 'Audio not loaded'
: isPlaying
? 'Pause'
: 'Play'
}
>
{isPlaying ? <Pause className="h-5 w-5" /> : <Play className="h-5 w-5" />}
</Button>
Expand All @@ -845,6 +853,8 @@ export function AudioPlayer() {
max={100}
step={0.1}
className="w-full"
aria-label="Playback position"
aria-valuetext={`${formatAudioDuration(currentTime)} of ${formatAudioDuration(duration)}`}
/>
)}
{isLoading && (
Expand Down Expand Up @@ -872,26 +882,33 @@ export function AudioPlayer() {
onClick={toggleLoop}
className={isLooping ? 'text-primary' : ''}
title="Toggle loop"
aria-label={isLooping ? 'Stop looping' : 'Loop'}
>
<Repeat className="h-4 w-4" />
</Button>

{/* Volume Control */}
<div className="flex items-center gap-2 shrink-0 w-[120px]">
<div className="flex items-center gap-2 shrink-0 w-[120px]" role="group" aria-label="Volume">
<Button
variant="ghost"
size="icon"
onClick={() => setVolume(volume > 0 ? 0 : 1)}
className="h-8 w-8"
aria-label={volume > 0 ? 'Mute' : 'Unmute'}
>
{volume > 0 ? <Volume2 className="h-4 w-4" /> : <VolumeX className="h-4 w-4" />}
</Button>
<span id={volumeLabelId} className="sr-only">
Volume level, {Math.round(volume * 100)}%
</span>
<Slider
value={[volume * 100]}
onValueChange={handleVolumeChange}
max={100}
step={1}
className="flex-1"
aria-labelledby={volumeLabelId}
aria-valuetext={`${Math.round(volume * 100)}%`}
/>
</div>

Expand All @@ -902,6 +919,7 @@ export function AudioPlayer() {
onClick={handleClose}
className="shrink-0"
title="Close player"
aria-label="Close player"
>
<X className="h-5 w-5" />
</Button>
Expand Down
12 changes: 12 additions & 0 deletions app/src/components/Generation/FloatingGenerateBox.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,13 @@ export function FloatingGenerateBox({
disabled={isPending || !selectedProfileId}
className="h-10 w-10 rounded-full bg-accent hover:bg-accent/90 hover:scale-105 text-accent-foreground shadow-lg hover:shadow-accent/50 transition-all duration-200"
size="icon"
aria-label={
isPending
? 'Generating...'
: !selectedProfileId
? 'Select a voice profile first'
: 'Generate speech'
}
>
{isPending ? (
<Loader2 className="h-4 w-4 animate-spin" />
Expand Down Expand Up @@ -336,6 +343,11 @@ export function FloatingGenerateBox({
? 'bg-accent text-accent-foreground border border-accent hover:bg-accent/90'
: 'bg-card border border-border hover:bg-background/50',
)}
aria-label={
isInstructMode
? 'Fine tune instructions, on'
: 'Fine tune instructions'
}
>
<SlidersHorizontal className="h-4 w-4" />
</Button>
Expand Down
16 changes: 16 additions & 0 deletions app/src/components/History/HistoryTable.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,10 +253,17 @@ export function HistoryTable() {
return (
<div
key={gen.id}
role="button"
tabIndex={0}
className={cn(
'flex items-stretch gap-4 h-26 border rounded-md p-3 bg-card hover:bg-muted/70 transition-colors text-left w-full',
isCurrentlyPlaying && 'bg-muted/70',
)}
aria-label={
isCurrentlyPlaying
? `Sample from ${gen.profile_name}, ${formatDuration(gen.duration)}, ${formatDate(gen.created_at)}. Playing. Press Enter to restart.`
: `Sample from ${gen.profile_name}, ${formatDuration(gen.duration)}, ${formatDate(gen.created_at)}. Press Enter to play.`
}
onMouseDown={(e) => {
// Don't trigger play if clicking on textarea or if text is selected
const target = e.target as HTMLElement;
Expand All @@ -265,6 +272,14 @@ export function HistoryTable() {
}
handlePlay(gen.id, gen.text, gen.profile_id);
}}
onKeyDown={(e) => {
const target = e.target as HTMLElement;
if (target.closest('textarea')) return;
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
handlePlay(gen.id, gen.text, gen.profile_id);
}
}}
Comment on lines +275 to +282
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Skip the row shortcut when focus is inside child controls.

onKeyDown only excludes the transcript, so Enter/Space on the Actions trigger will also play or restart the sample. The mouse path is protected with stopPropagation(), but the keyboard path still bubbles to the row handler.

💡 Minimal guard 
                  onKeyDown={(e) => {
-                   const target = e.target as HTMLElement;
-                   if (target.closest('textarea')) return;
+                   if (e.target !== e.currentTarget) return;
                    if (e.key === 'Enter' || e.key === ' ') {
                      e.preventDefault();
                      handlePlay(gen.id, gen.text, gen.profile_id);
                    }
                  }}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
onKeyDown={(e) => {
const target = e.target as HTMLElement;
if (target.closest('textarea')) return;
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
handlePlay(gen.id, gen.text, gen.profile_id);
}
}}
onKeyDown={(e) => {
if (e.target !== e.currentTarget) return;
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
handlePlay(gen.id, gen.text, gen.profile_id);
}
}}
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@app/src/components/History/HistoryTable.tsx` around lines 275 - 282, The
row-level onKeyDown handler currently only ignores textarea children so
Enter/Space pressed on action controls still triggers handlePlay; update the
guard in that onKeyDown to detect and return early when the event target is
inside any interactive child (e.g., closest('input, button, select, textarea, a,
[role="button"]') or a custom marker like [data-ignore-row-shortcut]) so
keyboard interactions on child controls don’t bubble to the row and call
handlePlay(gen.id, gen.text, gen.profile_id).

>
{/* Waveform icon */}
<div className="flex items-center shrink-0">
Expand Down Expand Up @@ -293,6 +308,7 @@ export function HistoryTable() {
value={gen.text}
className="flex-1 resize-none text-sm text-muted-foreground select-text"
readOnly
aria-label={`Transcript for sample from ${gen.profile_name}, ${formatDuration(gen.duration)}`}
/>
</div>

Expand Down
6 changes: 5 additions & 1 deletion app/src/components/ServerSettings/ConnectionForm.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,11 @@ export function ConnectionForm() {
}

return (
<Card>
<Card
role="region"
aria-label="Server Connection"
tabIndex={0}
>
<CardHeader>
<CardTitle>Server Connection</CardTitle>
</CardHeader>
Expand Down
34 changes: 30 additions & 4 deletions app/src/components/ServerSettings/ModelManagement.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,9 +278,25 @@ interface ModelItemProps {
function ModelItem({ model, onDownload, onDelete, isDownloading, formatSize }: ModelItemProps) {
// Use server's downloading state OR local state (for immediate feedback before server updates)
const showDownloading = model.downloading || isDownloading;


const statusText = model.loaded
? 'Loaded'
: showDownloading
? 'Downloading'
: model.downloaded
? 'Downloaded'
: 'Not downloaded';
const sizeText =
model.downloaded && model.size_mb && !showDownloading ? `, ${formatSize(model.size_mb)}` : '';
const rowLabel = `${model.display_name}, ${statusText}${sizeText}. Use Tab to reach Download or Delete.`;

return (
<div className="flex items-center justify-between p-3 border rounded-lg">
<div
className="flex items-center justify-between p-3 border rounded-lg"
role="group"
tabIndex={0}
aria-label={rowLabel}
>
<div className="flex-1">
<div className="flex items-center gap-2">
<span className="font-medium text-sm">{model.display_name}</span>
Expand Down Expand Up @@ -314,17 +330,27 @@ function ModelItem({ model, onDownload, onDelete, isDownloading, formatSize }: M
variant="outline"
disabled={model.loaded}
title={model.loaded ? 'Unload model before deleting' : 'Delete model'}
aria-label={
model.loaded
? 'Unload model before deleting'
: `Delete ${model.display_name}`
}
>
<Trash2 className="h-4 w-4" />
</Button>
</div>
) : showDownloading ? (
<Button size="sm" variant="outline" disabled>
<Button size="sm" variant="outline" disabled aria-label={`${model.display_name} downloading`}>
<Loader2 className="h-4 w-4 mr-2 animate-spin" />
Downloading...
</Button>
) : (
<Button size="sm" onClick={onDownload} variant="outline">
<Button
size="sm"
onClick={onDownload}
variant="outline"
aria-label={`Download ${model.display_name}`}
>
<Download className="h-4 w-4 mr-2" />
Download
</Button>
Expand Down
6 changes: 5 additions & 1 deletion app/src/components/ServerSettings/ServerStatus.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,11 @@ export function ServerStatus() {
const serverUrl = useServerStore((state) => state.serverUrl);

return (
<Card>
<Card
role="region"
aria-label="Server Status"
tabIndex={0}
>
<CardHeader>
<CardTitle>Server Status</CardTitle>
</CardHeader>
Expand Down
6 changes: 5 additions & 1 deletion app/src/components/ServerSettings/UpdateStatus.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,11 @@ export function UpdateStatus() {
}, [platform]);

return (
<Card>
<Card
role="region"
aria-label="App Updates"
tabIndex={0}
>
<CardHeader>
<CardTitle>App Updates</CardTitle>
</CardHeader>
Expand Down
22 changes: 15 additions & 7 deletions app/src/components/StoriesTab/StoryList.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,17 +194,24 @@ export function StoryList() {
storyList.map((story) => (
<div
key={story.id}
role="button"
tabIndex={0}
className={cn(
'h-24 p-4 border rounded-2xl transition-colors group flex items-center',
'h-24 p-4 border rounded-2xl transition-colors group flex items-center cursor-pointer',
selectedStoryId === story.id && 'bg-muted border-primary',
)}
aria-label={`Story ${story.name}, ${story.item_count} ${story.item_count === 1 ? 'item' : 'items'}, ${formatDate(story.updated_at)}. Press Enter to select.`}
onClick={() => setSelectedStoryId(story.id)}
onKeyDown={(e) => {
if (e.target !== e.currentTarget) return;
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
setSelectedStoryId(story.id);
}
}}
>
<div className="flex items-start justify-between gap-2 w-full min-w-0">
<button
type="button"
className="flex-1 min-w-0 text-left cursor-pointer overflow-hidden"
onClick={() => setSelectedStoryId(story.id)}
>
<div className="flex-1 min-w-0 text-left overflow-hidden">
<h3 className="font-medium truncate">{story.name}</h3>
{story.description && (
<p className="text-sm text-muted-foreground mt-1 truncate">
Expand All @@ -218,14 +225,15 @@ export function StoryList() {
<span>•</span>
<span>{formatDate(story.updated_at)}</span>
</div>
</button>
</div>
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button
variant="ghost"
size="icon"
className="h-8 w-8 opacity-0 group-hover:opacity-100 transition-opacity"
onClick={(e) => e.stopPropagation()}
aria-label={`Actions for ${story.name}`}
>
<MoreHorizontal className="h-4 w-4" />
</Button>
Expand Down
21 changes: 19 additions & 2 deletions app/src/components/StoriesTab/StoryTrackEditor.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -736,6 +736,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
className="h-7 w-7"
onClick={handlePlayPause}
title="Play/Pause (Space)"
aria-label={isCurrentlyPlaying ? 'Pause' : 'Play'}
>
{isCurrentlyPlaying ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
</Button>
Expand All @@ -745,6 +746,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
className="h-7 w-7"
onClick={handleStop}
disabled={!isCurrentlyPlaying}
aria-label="Stop"
>
<Square className="h-3 w-3" />
</Button>
Expand All @@ -762,6 +764,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
className="h-7 w-7"
onClick={handleSplit}
title="Split at playhead (S)"
aria-label="Split at playhead"
>
<Scissors className="h-4 w-4" />
</Button>
Expand All @@ -771,6 +774,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
className="h-7 w-7"
onClick={handleDuplicate}
title="Duplicate (Cmd/Ctrl+D)"
aria-label="Duplicate clip"
>
<Copy className="h-4 w-4" />
</Button>
Expand All @@ -780,6 +784,7 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
className="h-7 w-7"
onClick={handleDelete}
title="Delete (Delete/Backspace)"
aria-label="Delete clip"
>
<Trash2 className="h-4 w-4" />
</Button>
Expand All @@ -789,10 +794,22 @@ export function StoryTrackEditor({ storyId, items }: StoryTrackEditorProps) {
{/* Zoom controls - right side */}
<div className="flex items-center gap-2">
<span className="text-xs text-muted-foreground">Zoom:</span>
<Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleZoomOut}>
<Button
variant="ghost"
size="icon"
className="h-6 w-6"
onClick={handleZoomOut}
aria-label="Zoom out"
>
<Minus className="h-3 w-3" />
</Button>
<Button variant="ghost" size="icon" className="h-6 w-6" onClick={handleZoomIn}>
<Button
variant="ghost"
size="icon"
className="h-6 w-6"
onClick={handleZoomIn}
aria-label="Zoom in"
>
<Plus className="h-3 w-3" />
</Button>
</div>
Expand Down
8 changes: 7 additions & 1 deletion app/src/components/VoiceProfiles/AudioSampleRecording.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,13 @@ export function AudioSampleRecording({
</div>
<p className="text-sm text-muted-foreground text-center">File: {file.name}</p>
<div className="flex gap-2">
<Button type="button" size="icon" variant="outline" onClick={onPlayPause}>
<Button
type="button"
size="icon"
variant="outline"
onClick={onPlayPause}
aria-label={isPlaying ? 'Pause' : 'Play'}
>
{isPlaying ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
</Button>
<Button
Expand Down
8 changes: 7 additions & 1 deletion app/src/components/VoiceProfiles/AudioSampleSystem.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,13 @@ export function AudioSampleSystem({
</div>
<p className="text-sm text-muted-foreground text-center">File: {file.name}</p>
<div className="flex gap-2">
<Button type="button" size="icon" variant="outline" onClick={onPlayPause}>
<Button
type="button"
size="icon"
variant="outline"
onClick={onPlayPause}
aria-label={isPlaying ? 'Pause' : 'Play'}
>
{isPlaying ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
</Button>
<Button
Expand Down
1 change: 1 addition & 0 deletions app/src/components/VoiceProfiles/AudioSampleUpload.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ export function AudioSampleUpload({
variant="outline"
onClick={onPlayPause}
disabled={isValidating}
aria-label={isPlaying ? 'Pause' : 'Play'}
>
{isPlaying ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
</Button>
Expand Down
Loading