fix(theme): improve accessibility of api explorer controls

[emroussel]

Description

Fix a couple of accessibility violations in the openapi explorer:

• Associate form controls like inputs and selects to their label: I created a new <FormLabel> component to do this since I couldn't find a good way to make this work with the existing <FormItem> component. Some spots didn't render a visual label so I just set an aria-label or aria-labelledby as to not introduce any UI changes.
• Use buttons instead of spans for the buttons next to the title in the request and response sections: Previously these "collapse/expand all" and "clear" interactive elements were impossible to focus/trigger using a keyboard.
• Implement the disclosure pattern on the "show/hide optional params" button: Looks like all other disclosures use <details>/<summary> so the ideal fix here would probably be to do the same, but I wanted to keep markup changes to a minimum so I added the required aria attributes to make it accessible to screen readers instead.
• Remove outline: none from the delete and add item buttons in array param form items: Removing the outline makes it so that users who navigate the site using a keyboard cannot know what is currently being focused.

Motivation and Context

Closes #1265

How Has This Been Tested?

Tested the openapi explorer section of the pet store demo running locally with keyboard navigation, screen reader, and mouse. Compared markup and styles with previous version (without my changes) to make it looks the same and that markup is not changed significantly.

Screenshots (if appropriate)

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)

Note: some of these fixes change the markup/styles slightly, for example I updated a clickable <span> to use a <button> instead since that's better semantics, but it could also be kept as a span with attributes like role="button" and tabindex="0" instead if you would rather keep markup changes to an absolute minimum. Some changes are probably inevitable though.

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[sserrata]

Hi @emroussel, thanks for the contribution! Only one minor nit (see below) before we can merge:

1. TypeScript validity of htmlFor on (FormLabel/index.tsx:387)
   const LabelTag = htmlFor ? "label" : "span";

Passing htmlFor to a is not valid HTML and may cause a TS error depending on the tsconfig. A safer pattern would be:

  return htmlFor ? (                                                                                                                       
    <label htmlFor={htmlFor} className="...">...</label>                                                                                   
  ) : (                                                                                                                                    
    <span className="...">...</span>                                                                                                       
  );  

[emroussel]

@sserrata good catch, should be fixed now

[github-actions]

Visit the preview URL for this PR (updated for commit b522efe):

https://docusaurus-openapi-36b86--pr1325-jqeqjb62.web.app

_{(expires Sat, 25 Apr 2026 16:37:48 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}