[A11Y] [Low] AsciinemaPlayer component accessibility improvements

[continue]

Accessibility Issue: AsciinemaPlayer component accessibility improvements

WCAG Level: A
Severity: Low
Category: Media Accessibility / Dynamic Content

Issue Description

The AsciinemaPlayer component embeds terminal recordings but may lack proper accessibility features for screen reader users and keyboard navigation. The component creates a div that holds the player but doesn't provide:

1. An accessible label for the player container
2. Fallback content for users who cannot view the recording
3. Keyboard instructions for controlling playback

User Impact

• Affected Users: Screen reader users, keyboard-only users, users who cannot view animations
• Severity: Users may not understand the content of terminal recordings

Violations Found

File: src/components/AsciinemaPlayer/AsciinemaPlayer.tsx

Lines: 38-44

return (
  <BrowserOnly>
    {
      () => {
        // ...
        return <div ref={ref} style={style} />;
      }
    }
  </BrowserOnly>
)

Issue:

1. The player container div has no accessible label
2. No fallback content when player is unavailable
3. No description of what the recording demonstrates

---

Recommended Fix

type AsciinemaPlayerProps = {
    src: string;
    style: React.CSSProperties;
    title?: string;          // Add accessible title
    description?: string;    // Add accessible description
    // ... other props
};

const AsciinemaPlayer: React.FC<AsciinemaPlayerProps> = ({
    src,
    style,
    title,
    description,
    ...asciinemaOptions
}) => {
  return (
    <BrowserOnly
      fallback={
        <div role="img" aria-label={title || "Terminal recording"}>
          <p>{description || "Terminal recording - content available in browser"}</p>
        </div>
      }
    >
      {
        () => {
          if (!ExecutionEnvironment.canUseDOM) {
              return (
                <div role="img" aria-label={title || "Terminal recording"}>
                  ASCII Cinema Player Unavailable
                </div>
              );
          }
          const AsciinemaPlayerLibrary = require('asciinema-player');
          const ref = useRef<HTMLDivElement>(null);

          useEffect(() => {
            const currentRef = ref.current;
            AsciinemaPlayerLibrary.create(src, currentRef, asciinemaOptions);
          }, [src]);

          return (
            <div 
              ref={ref} 
              style={style}
              role="img"
              aria-label={title || "Terminal recording"}
              aria-describedby={description ? `${src}-desc` : undefined}
            >
              {description && (
                <span id={`${src}-desc`} className="visually-hidden">
                  {description}
                </span>
              )}
            </div>
          );
        }
      }
    </BrowserOnly>
  )
};

Changes Made:

1. Added title and description props for accessibility
2. Added role="img" and aria-label to the container
3. Improved fallback content for SSR/no-JS scenarios
4. Added aria-describedby for longer descriptions

Usage Example

<AsciinemaPlayer
  src="/casts/example.cast"
  title="Installing shell samples"
  description="This recording demonstrates how to download and extract the effective shell samples using curl and tar commands."
  style={{ width: '100%' }}
/>

Testing Instructions

1. Enable a screen reader
2. Navigate to a page with an AsciinemaPlayer component
3. Verify the screen reader announces the title/purpose of the recording
4. Test keyboard navigation within the player
5. Disable JavaScript and verify fallback content appears

Resources

• WCAG 1.1.1 Non-text Content
• MDN: aria-label
• Asciinema accessibility

Acceptance Criteria

• AsciinemaPlayer has accessible title prop
• Fallback content provided for non-JS environments
• Screen reader announces recording purpose
• Keyboard controls documented or accessible
• Manual testing with screen reader completed

---