doc: Add a11y labels to copy/stackblitz buttons on the remaining components (#3417)

Co-authored-by: Maxime Lardenois <maxime.lardenois@orange.com>

Author: hannahiss

site/src/components/shortcodes/JsDismiss.astro

@@ -7,6 +7,8 @@ interface Props {
 }
 
 const { name } = Astro.props
+const withinButtonLabel = `dismissal button within the ${name}`
+const outsideButtonLabel = `dismissal button outside the ${name}`
 ---
 
 <p>
@@ -15,7 +17,7 @@ const { name } = Astro.props
   > as demonstrated below:
 </p>
 
-<Code
+<Code buttonLabel={withinButtonLabel}
   code={`<button class="btn btn-icon btn-minimal" data-bs-dismiss="${name}">\n  <svg aria-hidden="true"><use xlink:href="${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#expurge')}"/></svg>\n  <span class="visually-hidden">Close</span>\n</button>`}
   lang="html"
 />
@@ -24,7 +26,7 @@ const { name } = Astro.props
   or on a button <strong>outside the {name}</strong> using the additional <code>data-bs-target</code> as demonstrated below:
 </p>
 
-<Code
+<Code buttonLabel={outsideButtonLabel}
   code={`<button class="btn btn-icon btn-minimal" data-bs-dismiss="${name}" data-bs-target="#my-${name}">\n  <svg aria-hidden="true"><use xlink:href="${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#expurge')}"/></svg>\n  <span class="visually-hidden">Close</span>\n</button>`}
   lang="html"
 />

site/src/content/docs/components/alerts.mdx

@@ -192,7 +192,7 @@ The variants `.alert-negative`, `.alert-positive`, `.alert-info` and `.alert-war
   </div>`} />
 
 <BootstrapCompatibility>
-<Example class="d-flex flex-column gap-medium" code={`<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
+<Example buttonLabel="Bootstrap compatibility: functional alert message" class="d-flex flex-column gap-medium" code={`<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
     <symbol id="check-circle-fill" viewBox="0 0 16 16">
       <path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z"/>
     </symbol>
@@ -256,7 +256,7 @@ The variants alert neutral (default) and `.alert-accent` are considered as non-f
   </div>`} />
 
 <BootstrapCompatibility>
-<Example class="d-flex flex-column gap-medium" code={`<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
+<Example buttonLabel="Bootstrap compatibility: non-functional alert message" class="d-flex flex-column gap-medium" code={`<svg xmlns="http://www.w3.org/2000/svg" class="d-none">
     <symbol id="info-fill" viewBox="0 0 16 16">
       <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/>
     </symbol>
@@ -283,7 +283,7 @@ In any case, the icon will be colorized automatically via the `color` attribute.
 
 <Callout type="info" name="info-icons-svg-sprite" />
 
-<Example buttonLabel="changed icon alert message" class="d-flex flex-column gap-medium" code={`<div class="alert alert-message">
+<Example buttonLabel="custom icon alert message" class="d-flex flex-column gap-medium" code={`<div class="alert alert-message">
     <div class="alert-icon">
       <svg aria-hidden="true">
         <use xlink:href="${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#heart-empty')}"/>
@@ -650,10 +650,8 @@ We use the following JavaScript to trigger our live alert demo:
 
 Initialize elements as alerts.
 
-```js
-const alertList = document.querySelectorAll('.alert')
-const alerts = [...alertList].map(element => new oudsWeb.Alert(element))
-```
+<Code buttonLabel="alerts initialization" lang="js" code={`const alertList = document.querySelectorAll('.alert')
+  const alerts = [...alertList].map(element => new oudsWeb.Alert(element))`} />
 
 <Callout type="info">
   For the sole purpose of dismissing an alert, it isn’t necessary to initialize the component manually via the JS API, unless you want to use one of our [methods](#methods). By making use of `data-bs-dismiss="alert"`, the component will be initialized automatically and properly dismissed.
@@ -671,9 +669,7 @@ const alerts = [...alertList].map(element => new oudsWeb.Alert(element))
 
 You can create an alert instance with the alert constructor, for example:
 
-```js
-const bsAlert = new oudsWeb.Alert('#myAlert')
-```
+<Code buttonLabel="alert instance creation" lang="js" code={`const bsAlert = new oudsWeb.Alert('#myAlert')`} />
 
 This makes an alert listen for click events on descendant elements which have the `data-bs-dismiss="alert"` attribute. (Not necessary when using the data-api’s auto-initialization.)
 
@@ -688,10 +684,8 @@ This makes an alert listen for click events on descendant elements which have th
 
 Basic usage:
 
-```js
-const alert = oudsWeb.Alert.getOrCreateInstance('#myAlert')
-alert.close()
-```
+<Code buttonLabel="alert basic usage" lang="js" code={`const alert = oudsWeb.Alert.getOrCreateInstance('#myAlert')
+  alert.close()`} />
 
 #### Events
 
@@ -704,14 +698,12 @@ OUDS Web’s alert plugin exposes a few events for hooking into alert functional
 | `closed.bs.alert` | Fired when the alert has been closed and CSS transitions have completed. |
 </BsTable>
 
-```js
-const myAlert = document.getElementById('myAlert')
+<Code buttonLabel="events listening" lang="js" code={`const myAlert = document.getElementById('myAlert')
 myAlert.addEventListener('closed.bs.alert', event => {
   // do something, for instance, explicitly move focus to the most appropriate element,
   // so it doesn’t get lost/reset to the start of the page
   // document.getElementById('...').focus()
-})
-```
+})`} />
 
 ## [[comp]] Inline alert
 

site/src/content/docs/components/badges.mdx

@@ -93,7 +93,7 @@ Badge is displayed as a coloured shape, without an icon, text, or number; its se
   If the context does not allow visually impaired or blind users to understand the meaning, add a `.visually-hidden` text associated with the badge. [Read more about badges accessibility here](#accessibility).
 </Callout>
 
-<Example class="" code={`<p class="badge"><span class="visually-hidden">Beware</span></p>
+<Example buttonLabel="badges accessible usage" code={`<p class="badge"><span class="visually-hidden">Beware</span></p>
   <p class="d-flex align-items-center">Beware<span class="badge ms-2xsmall"></span></p>`} />
 
 ### Variants
@@ -104,7 +104,7 @@ Badge is displayed as a coloured shape, without an icon, text, or number; its se
 
 Non-functional badges are used to display neutral or accent information without carrying a specific functional meaning (unlike functional badges, see below).
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-neutral"><span class="visually-hidden">To be noted</span></p>
+<Example buttonLabel="non-functional badges" class="d-flex gap-large" code={`<p class="badge badge-neutral"><span class="visually-hidden">To be noted</span></p>
   <p class="badge badge-accent"><span class="visually-hidden">Important</span></p>`} />
 
 ##### Functional
@@ -115,14 +115,14 @@ Functional badges carry a clear meaning related to the status of an object or sy
   Keep in mind that color should not be the only way to convey information. Functional badges, which have a strong meaning, should not be combined, because  some users cannot differentiate colors between them, for example colorblind people. In this case, it is preferable to use an icon as a second way to convey information, associated with a `.visually-hidden` text (required for screen reader users). [Read more about badges accessibility here](#accessibility).
 </Callout>
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-positive"><span class="visually-hidden">Success</span></p>
+<Example buttonLabel="functional badges" class="d-flex gap-large" code={`<p class="badge badge-positive"><span class="visually-hidden">Success</span></p>
   <p class="badge badge-info"><span class="visually-hidden">Info</span></p>
   <p class="badge badge-warning"><span class="visually-hidden">Warning</span></p>
   <p class="badge"><span class="visually-hidden">Beware</span></p>`} />
 
 Here is a valid example of use of functional badges:
 
-<Example class="d-flex gap-large" code={`<div class="d-flex align-items-center">
+<Example buttonLabel="functional badges usage" class="d-flex gap-large" code={`<div class="d-flex align-items-center">
     <p class="position-relative mb-none">
       Activities<span class="badge badge-info badge-small ms-2xsmall"></span><span class="visually-hidden">New!</span>
     </p>
@@ -146,7 +146,7 @@ Here is a valid example of use of functional badges:
 
 The disabled state of a badge appears visually muted to signal that it is not currently active or relevant. To make a disabled badge, simply add the `.badge-disabled` class. Depending on the use case, the `.visually-hidden` text may be unnecessary or require adaptation.
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-neutral badge-disabled"></p>
+<Example buttonLabel="disabled badges" class="d-flex gap-large" code={`<p class="badge badge-neutral badge-disabled"></p>
   <p class="badge badge-accent badge-disabled"></p>
   <p class="badge badge-positive badge-disabled"></p>
   <p class="badge badge-info badge-disabled"></p>
@@ -157,7 +157,7 @@ The disabled state of a badge appears visually muted to signal that it is not cu
 
 Badges are available in four sizes. Default size is medium.
 
-<Example class="d-flex align-items-center gap-large" code={`
+<Example buttonLabel="badges sizes" class="d-flex align-items-center gap-large" code={`
   <p class="badge badge-xsmall"><span class="visually-hidden">Very small badge</span></p>
   <p class="badge badge-small"><span class="visually-hidden">Small badge</span></p>
   <p class="badge"><span class="visually-hidden">Medium badge (default)</span></p>
@@ -173,7 +173,7 @@ Badge - count is displayed as a coloured shape that shows numerical values, and
   If the number itself is not meaningful in the context, add a `.visually-hidden` text associated with the badge - count. [Read more about badges accessibility here](#accessibility).
 </Callout>
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-count">1<span class="visually-hidden">error</span></p>
+<Example buttonLabel="badges count" class="d-flex gap-large" code={`<p class="badge badge-count">1<span class="visually-hidden">error</span></p>
   <p class="position-relative pt-3xsmall">
     Error<span class="position-absolute top-0 start-100 translate-middle badge badge-count">1</span>
   </p>`} />
@@ -188,7 +188,7 @@ Badges - count can be used with non-functional or functional colors.
   Keep in mind that color should not be the only way to convey information. If the color has a strong meaning, especially in functional statuses, reflect that meaning in the `.visually hidden` text associated with the badge - count. [Read more about badges accessibility here](#accessibility).
 </Callout>
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-neutral badge-count">0<span class="visually-hidden">notification</span></p>
+<Example buttonLabel="status badges count" class="d-flex gap-large" code={`<p class="badge badge-neutral badge-count">0<span class="visually-hidden">notification</span></p>
   <p class="badge badge-accent badge-count">1<span class="visually-hidden">notification</span></p>
   <p class="badge badge-positive badge-count">2<span class="visually-hidden">confirmations</span></p>
   <p class="badge badge-info badge-count">10<span class="visually-hidden">new emails</span></p>
@@ -201,7 +201,7 @@ Badges - count can be used with non-functional or functional colors.
 
 The disabled state of a badge - count appears visually muted to signal that it is not currently active or relevant. To make a disabled badge - count, simply add the `.badge-disabled` class. Depending on the use case, the `.visually-hidden` text may require adaptation.
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-neutral badge-count badge-disabled">0<span class="visually-hidden">notification</span></p>
+<Example buttonLabel="disabled badges count" class="d-flex gap-large" code={`<p class="badge badge-neutral badge-count badge-disabled">0<span class="visually-hidden">notification</span></p>
   <p class="badge badge-accent badge-count badge-disabled">1<span class="visually-hidden">notification</span></p>
   <p class="badge badge-positive badge-count badge-disabled">2<span class="visually-hidden">confirmations</span></p>
   <p class="badge badge-info badge-count badge-disabled">10<span class="visually-hidden">new emails</span></p>
@@ -212,7 +212,7 @@ The disabled state of a badge - count appears visually muted to signal that it i
 
 Badges - count are available in two sizes. Add `.badge-large` to have a larger badge. Default size is medium.
 
-<Example class="d-flex align-items-center gap-large" code={`<p class="badge badge-count">12<span class="visually-hidden">errors</span></p>
+<Example buttonLabel="badges count sizes" class="d-flex align-items-center gap-large" code={`<p class="badge badge-count">12<span class="visually-hidden">errors</span></p>
   <p class="badge badge-count badge-large">12<span class="visually-hidden">errors</span></p>`} />
 
 ## [[comp]] Badge - Icon
@@ -227,7 +227,7 @@ Badge - icon is presented as a coloured shape that displays an icon, and its sel
   Badges - icon should always be associated to a `.visually-hidden` text describing the icon's meaning. [Read more about badges accessibility here](#accessibility).
 </Callout>
 
-<Example class="d-flex align-items-center gap-large" code={`<p class="badge">
+<Example buttonLabel="badges icon" class="d-flex align-items-center gap-large" code={`<p class="badge">
     <span class="badge-status-icon"></span>
     <span class="visually-hidden">Beware</span>
   </p>
@@ -250,7 +250,7 @@ Badge - icon is presented as a coloured shape that displays an icon, and its sel
 
 Non-functional badges - icon are used to display neutral or accent information without carrying a specific functional meaning (unlike functional badges, see below), reinforced by an icon.
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-neutral">
+<Example buttonLabel="non-functional badges icon" class="d-flex gap-large" code={`<p class="badge badge-neutral">
     <svg class="badge-icon" aria-hidden="true">
       <use xlink:href="${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#heart-empty')}"/>
     </svg>
@@ -279,7 +279,7 @@ Functional badges - icon carry a clear meaning related to the status of an objec
   Keep in mind that color and icon should not be the only ways to convey information. In functional badges, the color and icon have a strong meaning, it must be reflected in the badge's `.visually-hidden` associated text. [Read more about tags accessibility here](#accessibility).
 </Callout>
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-positive">
+<Example buttonLabel="functional badges icon" class="d-flex gap-large" code={`<p class="badge badge-positive">
     <span class="badge-status-icon"></span>
     <span class="visually-hidden">Success</span>
   </p>
@@ -302,7 +302,7 @@ Functional badges - icon carry a clear meaning related to the status of an objec
 
 The disabled state of a badge - icon appears visually muted to signal that it is not currently active or relevant. To make a disabled badge - icon, simply add the `.badge-disabled` class. Depending on the use case, the `.visually-hidden` text may be unnecessary or require adaptation.
 
-<Example class="d-flex gap-large" code={`<p class="badge badge-disabled">
+<Example buttonLabel="disabled badges icon" class="d-flex gap-large" code={`<p class="badge badge-disabled">
     <span class="badge-status-icon"></span>
   </p>
   <p class="badge badge-neutral badge-disabled">
@@ -318,7 +318,7 @@ The disabled state of a badge - icon appears visually muted to signal that it is
 
 Badges - icon are available in two sizes. Add `.badge-large` to have a larger badge. Default size is medium.
 
-<Example class="d-flex align-items-center gap-large" code={`<p class="badge">
+<Example buttonLabel="badges icon sizes" class="d-flex align-items-center gap-large" code={`<p class="badge">
     <span class="badge-status-icon"></span>
     <span class="visually-hidden">Error</span>
   </p>
@@ -347,7 +347,7 @@ Badges - icon are available in two sizes. Add `.badge-large` to have a larger ba
 
 Use utilities to modify a `.badge` and position it in the corner of a button.
 
-<Example class="d-flex align-items-center gap-large" code={`<button type="button" class="btn btn-icon btn-default position-relative">
+<Example buttonLabel="badges positioning" class="d-flex align-items-center gap-large" code={`<button type="button" class="btn btn-icon btn-default position-relative">
     <svg class="icon" aria-hidden="true">
       <use xlink:href="${getVersionedDocsPath('/assets/img/ouds-web-sprite.svg#trash')}"/>
     </svg>
@@ -367,23 +367,21 @@ Use utilities to modify a `.badge` and position it in the corner of a button.
 
 <BootstrapCompatibility>
 
-<Example code={`<button type="button" class="btn btn-primary position-relative">
+<Example buttonLabel="Bootstrap compatibility: badge count positioning" code={`<button type="button" class="btn btn-primary position-relative">
     Inbox
     <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger">
       +99
       <span class="visually-hidden">unread messages</span>
     </span>
   </button>`} />
 
-<Example code={`<button type="button" class="btn btn-primary position-relative">
+<Example buttonLabel="Bootstrap compatibility: badge positioning" code={`<button type="button" class="btn btn-primary position-relative">
     Profile
     <span class="position-absolute top-0 start-100 translate-middle p-small bg-danger border border-light rounded-circle">
       <span class="visually-hidden">New alerts</span>
     </span>
   </button>`} />
 
-<Example code={getData('theme-colors').map((themeColor) => `<span class="badge text-bg-${themeColor.name}">+99</span>`)} />
-
-<Example code={getData('theme-colors').map((themeColor) => `<span class="badge rounded-pill text-bg-${themeColor.name}">+99</span>`)} />
+<Example buttonLabel="Bootstrap compatibility: badges count" code={getData('theme-colors').map((themeColor) => `<span class="badge text-bg-${themeColor.name}">+99</span>`)} />
 
 </BootstrapCompatibility>