From 076037a34968ac83379ae7a793019bf2ac11da9e Mon Sep 17 00:00:00 2001
From: Audrey Hamelers <audrey@datadryad.org>
Date: Tue, 14 Jul 2026 21:17:04 +0200
Subject: [PATCH] aria headings, labels, and announcements

---
 src/components/api-request.js             | 35 ++++++++++++-----------
 src/components/api-response.js            |  4 +--
 src/components/request-form-table.js      |  2 +-
 src/components/schema-tree.js             |  4 +--
 src/components/syntax-highlighter.js      |  9 ++++--
 src/templates/security-scheme-template.js | 16 +++++------
 src/templates/server-template.js          |  4 +--
 7 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/src/components/api-request.js b/src/components/api-request.js
index 33675a84..894d3dd8 100644
--- a/src/components/api-request.js
+++ b/src/components/api-request.js
@@ -302,7 +302,7 @@ export default class ApiRequest extends LitElement {
     }
 
     return html`
-    <div class="table-title top-gap">${title}${paramLocation === 'path' ? html`<span style='color:var(--red);'>*</span>` : ''}</div>
+    <div class="table-title top-gap" role="heading" aria-level="${this.renderStyle === 'focused' ? 4 : 5}">${title}${paramLocation === 'path' ? html`<span style='color:var(--red);'>*</span>` : ''}</div>
     <div style="display:block; overflow-x:auto; max-width:100%;">
       <table role="presentation" class="m-table" style="width:100%; word-break:break-word;">
         ${tableRows}
@@ -627,18 +627,21 @@ export default class ApiRequest extends LitElement {
         ${!hasResponse ? '' : html`<button class="m-btn" part="btn btn-outline" @click="${this.clearResponseData}">${getI18nText('operations.clear-response')}</button>`}
       </div>
       <div class="tab-panel col" style="border-width:0 0 1px 0;">
-        <div id="tab_buttons" class="tab-buttons row" @click="${(e) => {
-            if (e.target.classList.contains('tab-btn') === false) { return; }
-            this.activeResponseTab = e.target.dataset.tab;
-        }}">
-        <br>
-        <div style="width: 100%">
-        <button class="tab-btn ${!hasResponse || this.activeResponseTab === 'curl' ? 'active' : ''}" data-tab = 'curl'>${getI18nText('operations.request')}</button>
-          ${!hasResponse ? '' : html`
-            <button class="tab-btn ${this.activeResponseTab === 'response' ? 'active' : ''}" data-tab = 'response'>${getI18nText('operations.response')}</button>
-            <button class="tab-btn ${this.activeResponseTab === 'headers' ? 'active' : ''}"  data-tab = 'headers'>${getI18nText('operations.response-headers')}</button>`
-          }
-          </div>
+        ${hasResponse
+          ? html`
+            <div id="tab_buttons" class="tab-buttons row" role="group" @click="${(e) => {
+              if (e.target.classList.contains('tab-btn') === false) { return; }
+              this.activeResponseTab = e.target.dataset.tab;
+            }}">
+            <button class="tab-btn ${this.activeResponseTab === 'curl' ? 'active' : ''}" aria-current="${this.activeResponseTab === 'curl'}" data-tab = 'curl'>${getI18nText('operations.request')}</button>
+            <button class="tab-btn ${this.activeResponseTab === 'response' ? 'active' : ''}" aria-current="${this.activeResponseTab === 'response'}" data-tab = 'response'>${getI18nText('operations.response')}</button>
+            <button class="tab-btn ${this.activeResponseTab === 'headers' ? 'active' : ''}"  aria-current="${this.activeResponseTab === 'headers'}" data-tab = 'headers'>${getI18nText('operations.response-headers')}</button>
+            </div>`
+          : html`
+            <div id="tab_buttons" class="tab-buttons row">
+              <div class="tab-btn active" role="heading" aria-level="${this.renderStyle === 'focused' ? 4 : 5}" data-tab = 'curl'>${getI18nText('operations.request')}</div>
+            </div>`
+        }
         </div>
         ${this.responseIsBlob
           ? html`
@@ -659,14 +662,14 @@ export default class ApiRequest extends LitElement {
             </div>`
           : html`
             <div class="tab-content col m-markdown" style="flex:1; display:${this.activeResponseTab === 'response' ? 'flex' : 'none'};" >
-              <syntax-highlighter style="min-height: 60px" mime-type="${this.responseContentType}" .content="${this.responseText}"/>
+              <syntax-highlighter style="min-height: 60px" mime-type="${this.responseContentType}" .content="${this.responseText}" aria-label="Response text"/>
             </div>`
         }
         <div class="tab-content col m-markdown" style="flex:1;display:${this.activeResponseTab === 'headers' ? 'flex' : 'none'};" >
-          <syntax-highlighter style="min-height: 60px" language="http" .content="${this.responseHeaders}"/>
+          <syntax-highlighter style="min-height: 60px" language="http" .content="${this.responseHeaders}" aria-label="Response headers"/>
         </div>
         <div class="tab-content m-markdown col" style="flex:1;display:${this.activeResponseTab === 'curl' ? 'flex' : 'none'};">
-          <syntax-highlighter style="min-height: 60px" language="shell" .content="${curlSyntax.trim()}"/>
+          <syntax-highlighter style="min-height: 60px" language="shell" .content="${curlSyntax.trim()}" aria-label="Request example"/>
         </div>
       </div>`;
   }
diff --git a/src/components/api-response.js b/src/components/api-response.js
index 6b30e6fe..aa42c992 100644
--- a/src/components/api-response.js
+++ b/src/components/api-response.js
@@ -275,7 +275,7 @@ export default class ApiResponse extends LitElement {
         ? html`
           ${mimeRespDetails.examples[0].exampleSummary && mimeRespDetails.examples[0].exampleSummary.length > 80 ? html`<div style="padding: 4px 0"> ${mimeRespDetails.examples[0].exampleSummary} </div>` : ''}
           ${mimeRespDetails.examples[0].exampleDescription ? html`<div class="m-markdown-small" style="padding: 4px 0"> ${unsafeHTML(toMarkdown(mimeRespDetails.examples[0].exampleDescription || ''))} </div>` : ''}
-          <syntax-highlighter class='example-panel generic-tree pad-top-8' mime-type="${mimeRespDetails.examples[0].exampleType}" .content="${mimeRespDetails.examples[0].exampleValue}"/>`
+          <syntax-highlighter class='example-panel generic-tree pad-top-8' mime-type="${mimeRespDetails.examples[0].exampleType}" .content="${mimeRespDetails.examples[0].exampleValue}" aria-label="Response example"/>`
         : html`
           <span class = 'example-panel generic-tree ${this.renderStyle === 'read' ? 'border pad-8-16' : 'border-top pad-top-8'}'>
             <select aria-label='response body example' @change='${(e) => this.onSelectExample(e)}'>
@@ -287,7 +287,7 @@ export default class ApiResponse extends LitElement {
               <div class="example" data-example = '${v.exampleId}' style = "display: ${v.exampleId === mimeRespDetails.selectedExample ? 'block' : 'none'}">
                 ${v.exampleSummary && v.exampleSummary.length > 80 ? html`<div style="padding: 4px 0"> ${v.exampleSummary} </div>` : ''}
                 ${v.exampleDescription && v.exampleDescription !== v.exampleSummary ? html`<div class="m-markdown-small" style="padding: 4px 0"> ${unsafeHTML(toMarkdown(v.exampleDescription || ''))} </div>` : ''}
-                <syntax-highlighter mime-type="${v.exampleType}" .content="${v.exampleValue}"/>
+                <syntax-highlighter mime-type="${v.exampleType}" .content="${v.exampleValue}" aria-label="Response example"/>
               </div>  
             `)}
           </span>  
diff --git a/src/components/request-form-table.js b/src/components/request-form-table.js
index 0148e129..d5a0b4fe 100644
--- a/src/components/request-form-table.js
+++ b/src/components/request-form-table.js
@@ -48,7 +48,7 @@ function generateFormRows(data, options, dataType = 'object', key = '', descript
                   ${data['::type'] === 'xxx-of-option' || key.startsWith('::OPTION')
                     ? html`<span class="xxx-of-key">${keyLabel}</span><span class="${isOneOfLabel ? 'xxx-of-key' : 'xxx-of-descr'}">${keyDescr}</span>`
                     : isRequired
-                      ? html`<span class="key-label requiredStar" style="display:inline-block;" title="Required">${keyLabel}</span>`
+                      ? html`<span class="key-label requiredStar" style="display:inline-block;" role="img" aria-label=" (Required)" title="Required">${keyLabel}</span>`
                       : html`<span class="key-label" style="display:inline-block;">${keyLabel === '::props' ? '' : keyLabel}</span>`
                   }
             </div>
diff --git a/src/components/schema-tree.js b/src/components/schema-tree.js
index 97cca90c..35500636 100644
--- a/src/components/schema-tree.js
+++ b/src/components/schema-tree.js
@@ -249,7 +249,7 @@ export default class SchemaTree extends LitElement {
                 ? ''
                 : schemaLevel > 0
                   ? html`<span class="key-label">
-                      ${keyLabel.replace(/\*$/, '')}${keyLabel.endsWith('*') ? html`<span class="requiredStar" title="Required"></span>` : ''}:
+                      ${keyLabel.replace(/\*$/, '')}${keyLabel.endsWith('*') ? html`<span class="requiredStar" role="img" aria-label=" (Required)" title="Required"></span>` : ''}:
                     </span>`
                   : ''
             }
@@ -296,7 +296,7 @@ export default class SchemaTree extends LitElement {
       <div class="tr">
         <div class="td key ${deprecated ? 'deprecated' : ''}" style='min-width:${minFieldColWidth}px'>
           ${keyLabel.endsWith('*')
-            ? html`<span class="key-label requiredStar" title="Required">${keyLabel.substring(0, keyLabel.length - 1)}</span>:`
+            ? html`<span class="key-label requiredStar" role="img" aria-label=" (Required)" title="Required">${keyLabel.substring(0, keyLabel.length - 1)}</span>:`
             : key.startsWith('::OPTION')
               ? html`<span class='key-label xxx-of-key'>${keyLabel}</span><span class="xxx-of-descr">${keyDescr}</span>`
               : schemaLevel > 0
diff --git a/src/components/syntax-highlighter.js b/src/components/syntax-highlighter.js
index 633392fd..cf9cc659 100644
--- a/src/components/syntax-highlighter.js
+++ b/src/components/syntax-highlighter.js
@@ -47,6 +47,7 @@ class SyntaxHighlighter extends LitElement {
       content: { type: Object },
       language: { type: String, attribute: 'language' },
       mimeType: { type: String, attribute: 'mime-type' },
+      label: { type: String, attribute: 'aria-label' },
     };
   }
 
@@ -96,7 +97,7 @@ class SyntaxHighlighter extends LitElement {
   }
 
   render() {
-    return this.renderCopyWrapper(this.renderHighlight());
+    return this.renderCopyWrapper(this.renderHighlight(), this.label?.toLowerCase());
   }
 
   /**
@@ -123,11 +124,13 @@ class SyntaxHighlighter extends LitElement {
    * @param {*} content Content
    * @returns Content
    */
-  renderCopyWrapper(content) {
+  renderCopyWrapper(content, label) {
     return html`<div class="fs-exclude ph-no-capture" data-hj-suppress data-sl="mask" style="min-height: 2rem;">
       <button 
         class="m-btn outline-primary toolbar-copy-btn" 
-        @click='${this.copyToClipboard}' 
+        @click='${this.copyToClipboard}'
+        aria-label="Copy ${label}"
+        aria-live="polite"
         part="btn btn-fill btn-copy">${getI18nText('operations.copy')}</button>
         ${content}
     </div>`;
diff --git a/src/templates/security-scheme-template.js b/src/templates/security-scheme-template.js
index 7c6b829d..a9532f41 100644
--- a/src/templates/security-scheme-template.js
+++ b/src/templates/security-scheme-template.js
@@ -332,7 +332,7 @@ function renderSecurityScheme(v) {
           : html`Sends the <code>Authorization header</code> containing the token type <code style="text-transform: capitalize;">${v.scheme || 'bearer'}</code> followed by the <code>${v.bearerFormat ?? 'Token'}</code> string.`
         }
       </div>
-      <form style="height: 50px; margin-top: 1rem; padding: 10px 0; margin-bottom: 10px;">
+      <form style="height: 50px; margin-top: 1rem; padding: 10px 0; margin-bottom: 10px;" aria-live="polite">
         ${v.in === 'cookie'
           ? html`
           <div style="display: block">
@@ -343,7 +343,7 @@ function renderSecurityScheme(v) {
             </small>
           </div>`
           : !v.finalKeyValue ? html`
-              <input autocomplete="on" name="api-key" type="text" value="${v.value}" placeholder="${v.bearerFormat ?? 'api-token'}"
+              <input autocomplete="on" name="api-key" type="text" value="${v.value}"  aria-label="${v.bearerFormat ?? 'API token'}"
                 spellcheck="false" class="api-key-input fs-exclude ph-no-capture" data-hj-suppress data-sl="mask">
               <button type="submit" class="m-btn thin-border" style = "margin-left:5px;"
                 part = "btn btn-outline"
@@ -363,7 +363,7 @@ function renderSecurityScheme(v) {
           code { font-weight: bold; }
         </style>
         <div style="padding-top: 1rem">${unsafeHTML(getI18nText('authentication.http-basic-desc'))}</div>
-        <div style="height: 50px; margin-top: 1rem; padding: 10px 0; margin-bottom: 10px;">
+        <div style="height: 50px; margin-top: 1rem; padding: 10px 0; margin-bottom: 10px;" aria-role="status">
           <span class="blue-text" style="margin-right: 1rem">Key Applied</span>
           <button class="m-btn thin-border small" part="btn btn-outline" @click=${() => { v.finalKeyValue = ''; this.requestUpdate(); }}>${getI18nText('authentication.remove')}</button>
         </div>`;
@@ -407,7 +407,7 @@ export default function securitySchemeTemplate() {
         <slot name="authentication-header">
           <div class="sub-title regular-font" role="heading" aria-level="2">${getI18nText('headers.authentication')}</div>
         </slot>
-        <div class="small-font-size" style="display:flex; align-items: center; min-height:40px">
+        <div class="small-font-size" style="display:flex; align-items: center; min-height:40px" aria-role="status">
           ${providedApiKeys.length > 0
             ? html`
               <div class="blue-text"> ${providedApiKeys.length} API key applied </div>
@@ -498,20 +498,20 @@ export function pathSecurityTemplate(pathSecurityOptions) {
         securityDefs: andSecurityKeys1,
       });
     });
-    return html`<div class="security-info-button" data-content-id='auth' @click='${(e) => this.scrollToEventTarget(e, false)}'>
+    return html`<div class="security-info-button">
       <div style="position:relative; display:flex; min-width:350px; max-width:700px; justify-content: flex-end;">
-        <svg width="16" height="24" style="cursor: pointer;">
+        <svg width="16" height="24" style="cursor: pointer;" role="img" aria-label="Security">
           <g>
             <path style="fill: var(--fg3)" d="m13.8,8.5l0,-2.6l0,0c0,-3.2 -2.6,-5.8 -5.8,-5.8s-5.8,2.6 -5.8,5.8l0,0l0,2.6l-2.1,0l0,11.2l16,0l0,-11.2l-2.1,0l-0,0l0,0l0,0l-0,0zm-9.8,-2.6c0,0 0,0 0,0c0,-2.2 1.8,-4 4,-4c2.2,0 4,1.8 4,4c0,0 0,0 0,0l0,2.6l-8.03,0l0,-2.6l0,0l0,0z" />
           </g>
         </svg>
           ${orSecurityKeys1.map((orSecurityItem1, i) => html`
           ${i !== 0 ? html`<div style="padding:3px 4px;"> OR </div>` : ''}
-          <div class="security-tooltip tooltip" style="cursor: pointer;">
+          <div class="security-tooltip tooltip" style="cursor: pointer;" aria-describedby="tooltip-security-info" data-content-id="auth" role="link" tabindex="0" @click='${(e) => this.scrollToEventTarget(e, false)}' @keydown="${(e) => { if (e.key === 'Enter') { e.target.click(); }}}">
             <div style="padding:2px 4px; white-space:nowrap; text-overflow:ellipsis;max-width:150px; overflow:hidden;">
               <span part="anchor anchor-operation-security"> ${orSecurityItem1.securityTypes} </span>
             </div>
-            <div class="tooltip-text" style="position:absolute; color: var(--fg); top:26px; right:0; border:1px solid var(--border-color);padding:2px 4px; display:block;">
+            <div class="tooltip-text" id="tooltip-security-info" role="tooltip" style="position:absolute; color: var(--fg); top:26px; right:0; border:1px solid var(--border-color);padding:2px 4px; display:block;">
               ${orSecurityItem1.securityDefs.length > 1 ? html`<div>Requires <b>all</b> of the following </div>` : ''}
               <div style="padding-left: 8px">
                 ${orSecurityItem1.securityDefs.map((andSecurityItem, j) => html`
diff --git a/src/templates/server-template.js b/src/templates/server-template.js
index 81d49e2a..b6830ea1 100644
--- a/src/templates/server-template.js
+++ b/src/templates/server-template.js
@@ -78,8 +78,8 @@ export default function serverTemplate() {
   }
   return html`
   <section id = 'servers' part="section-servers" style="margin-top:24px; margin-bottom:24px;" class='regular-font observe-me section-padding ${this.renderStyle === 'read' ? 'section-gap--read-mode' : (this.renderStyle === 'focused' ? 'section-gap--focused-mode' : 'section-gap')}'>
-    <div class = 'sub-title' role="heading" aria-level="2">${getI18nText('headers.api-servers')}</div>
-    <div class = 'mono-font' style='margin: 12px 0; font-size:calc(var(--font-size-small) + 1px);'>
+    <div class = 'sub-title' role="heading" aria-level="2" id="servers-title">${getI18nText('headers.api-servers')}</div>
+    <div class = 'mono-font' style='margin: 12px 0; font-size:calc(var(--font-size-small) + 1px);' role='radiogroup' aria-labelledby='servers-title'>
       ${!this.resolvedSpec.servers || !this.resolvedSpec.servers.length
         ? ''
         : html`