From 0e141cdb46e9b79cb732743e4fe36aeb094f198f Mon Sep 17 00:00:00 2001
From: Hannah Issermann <hannah.issermann@orange.com>
Date: Mon, 13 Oct 2025 11:31:12 +0200
Subject: [PATCH 1/3] Add the possibility to pass an aria-label for Copy to
 clipboard and Edit on Stackblitz buttons in code examples

---
 site/src/components/shortcodes/Code.astro     | 29 +++++++++++--------
 site/src/components/shortcodes/Example.astro  | 16 +++++++---
 site/src/components/shortcodes/JsDocs.astro   | 12 ++++++--
 site/src/components/shortcodes/ScssDocs.astro | 12 ++++++--
 4 files changed, 47 insertions(+), 22 deletions(-)

diff --git a/site/src/components/shortcodes/Code.astro b/site/src/components/shortcodes/Code.astro
index ba2c61165f..3b4f5d6c0f 100644
--- a/site/src/components/shortcodes/Code.astro
+++ b/site/src/components/shortcodes/Code.astro
@@ -38,9 +38,16 @@ interface Props {
    * @default false
    */
   nestedInExample?: boolean
+  /**
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   */
+  buttonLabel?: string
 }
 
-const { class: className, code, containerClass, fileMatch, filePath, lang, nestedInExample = false } = Astro.props
+const { class: className, code, containerClass, fileMatch, filePath, lang, nestedInExample = false, buttonLabel } = Astro.props
+
+const clipboardLabel = buttonLabel ? `Copy ${buttonLabel} code to clipboard` : filePath ?
+  `Copy ${filePath} code to clipboard` : 'Copy code to clipboard'
 
 let codeToDisplay = filePath
   ? fs.readFileSync(path.join(process.cwd(), filePath), 'utf8')
@@ -62,17 +69,15 @@ if (filePath && fileMatch && codeToDisplay) {
 <script>
   import ClipboardJS from 'clipboard'
 
-  const btnTitle = 'Copy to clipboard'
-  const btnEdit = 'Edit on StackBlitz'
-
-  function snippetButtonTooltip(selector: string, title: string) {
+  function snippetButtonTooltip(selector: string, tooltipLabel: string) {
     document.querySelectorAll(selector).forEach((btn) => {
-      bootstrap.Tooltip.getOrCreateInstance(btn, { title })
+      bootstrap.Tooltip.getOrCreateInstance(btn, { title: tooltipLabel })
     })
   }
 
-  snippetButtonTooltip('.btn-clipboard', btnTitle)
-  snippetButtonTooltip('.btn-edit', btnEdit)
+  const clipboardTooltip = 'Copy to clipboard'
+  snippetButtonTooltip('.btn-clipboard', clipboardTooltip)
+  snippetButtonTooltip('.btn-edit', 'Edit on StackBlitz')
 
   const clipboard = new ClipboardJS('.btn-clipboard', {
     target: (trigger) => trigger.closest('.bd-code-snippet')?.querySelector('.highlight')!,
@@ -100,7 +105,7 @@ if (filePath && fileMatch && codeToDisplay) {
     event.trigger.addEventListener(
       'hidden.bs.tooltip',
       () => {
-        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+        tooltipBtn?.setContent({ '.tooltip-inner': clipboardTooltip })
       },
       { once: true }
     )
@@ -128,7 +133,7 @@ if (filePath && fileMatch && codeToDisplay) {
     event.trigger.addEventListener(
       'hidden.bs.tooltip',
       () => {
-        tooltipBtn?.setContent({ '.tooltip-inner': btnTitle })
+        tooltipBtn?.setContent({ '.tooltip-inner': clipboardTooltip })
       },
       { once: true }
     )
@@ -145,8 +150,8 @@ if (filePath && fileMatch && codeToDisplay) {
         )
         : (
           <div class="bd-clipboard">
-            <button type="button" class="btn-clipboard">
-              <svg class="bi" role="img" aria-label="Copy">
+            <button type="button" class="btn-clipboard" title={clipboardLabel}>
+              <svg class="bi" aria-hidden="true">
                 <use xlink:href="#clipboard" />
               </svg>
             </button>
diff --git a/site/src/components/shortcodes/Example.astro b/site/src/components/shortcodes/Example.astro
index 044e1af4d4..c254942e97 100644
--- a/site/src/components/shortcodes/Example.astro
+++ b/site/src/components/shortcodes/Example.astro
@@ -36,6 +36,10 @@ interface Props {
    * @default true
    */
   showPreview?: boolean
+  /**
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   */
+  buttonLabel?: string
 }
 
 const {
@@ -45,12 +49,16 @@ const {
   id,
   lang = 'html',
   showMarkup = true,
-  showPreview = true
+  showPreview = true,
+  buttonLabel
 } = Astro.props
 
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
 
+const stackblitzLabel = buttonLabel ? `Edit ${buttonLabel} code on StackBlitz` : 'Edit code on StackBlitz'
+const clipboardLabel = buttonLabel ? `Copy ${buttonLabel} code to clipboard` : 'Copy code to clipboard'
+
 const simplifiedMarkup = markup
   .replace(
     /<svg.*class="bd-placeholder-img(?:-lg)?(?: *?bd-placeholder-img-lg)? ?(.*?)".*?<\/svg>/g,
@@ -81,14 +89,14 @@ const simplifiedMarkup = markup
               <button
                 type="button"
                 class="btn-edit text-nowrap"
-                title="Try it on StackBlitz"
+                title={stackblitzLabel}
                 data-sb-js-snippet={addStackblitzJs ? true : undefined}
               >
                 <svg class="bi" aria-hidden="true">
                   <use xlink:href="#lightning-charge-fill" />
                 </svg>
               </button>
-              <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+              <button type="button" class="btn-clipboard mt-0 me-0" title={clipboardLabel}>
                 <svg class="bi" aria-hidden="true">
                   <use xlink:href="#clipboard" />
                 </svg>
@@ -96,7 +104,7 @@ const simplifiedMarkup = markup
             </div>
           </div>
         )}
-        <Code code={simplifiedMarkup} lang={lang} nestedInExample={true} />
+        <Code code={simplifiedMarkup} lang={lang} nestedInExample={true} buttonLabel={buttonLabel} />
       </>
     )
   }
diff --git a/site/src/components/shortcodes/JsDocs.astro b/site/src/components/shortcodes/JsDocs.astro
index 4430f21f88..87b8f4f752 100644
--- a/site/src/components/shortcodes/JsDocs.astro
+++ b/site/src/components/shortcodes/JsDocs.astro
@@ -15,9 +15,13 @@ interface Props {
    * File path that contains the content to display relative to the root of the repository.
    */
   file: string
+  /**
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   */
+  buttonLabel?: string
 }
 
-const { name, file } = Astro.props
+const { name, file, buttonLabel } = Astro.props
 
 if (!name || !file) {
   throw new Error(
@@ -25,6 +29,8 @@ if (!name || !file) {
   )
 }
 
+const clipboardLabel = buttonLabel ? `Copy ${buttonLabel} JS to clipboard` : `Copy ${name} JS to clipboard`
+
 let content: string
 
 try {
@@ -52,7 +58,7 @@ try {
 }
 ---
 
-<Code containerClass="bd-example-snippet bd-code-snippet bd-file-ref" code={content} lang="js">
+<Code containerClass="bd-example-snippet bd-code-snippet bd-file-ref" code={content} lang="js" buttonLabel={buttonLabel}>
   <div slot="pre" class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
     <a
       class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small"
@@ -61,7 +67,7 @@ try {
       {file}
     </a>
     <div class="d-flex ms-auto">
-      <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+      <button type="button" class="btn-clipboard mt-0 me-0" title={clipboardLabel}>
         <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"></use></svg>
       </button>
     </div>
diff --git a/site/src/components/shortcodes/ScssDocs.astro b/site/src/components/shortcodes/ScssDocs.astro
index 4eaa8ca01f..f12a9161f6 100644
--- a/site/src/components/shortcodes/ScssDocs.astro
+++ b/site/src/components/shortcodes/ScssDocs.astro
@@ -15,9 +15,13 @@ interface Props {
    * File path that contains the content to display relative to the root of the repository.
    */
   file: string
+  /**
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   */
+  buttonLabel?: string
 }
 
-const { name, file } = Astro.props
+const { name, file, buttonLabel } = Astro.props
 
 if (!name || !file) {
   throw new Error(
@@ -25,6 +29,8 @@ if (!name || !file) {
   )
 }
 
+const clipboardLabel = buttonLabel ? `Copy ${buttonLabel} SCSS to clipboard` : `Copy ${name} SCSS to clipboard`
+
 let content: string
 
 try {
@@ -54,7 +60,7 @@ try {
 }
 ---
 
-<Code containerClass="bd-example-snippet bd-file-ref" code={content} lang="scss">
+<Code containerClass="bd-example-snippet bd-file-ref" code={content} lang="scss" buttonLabel={buttonLabel}>
   <div slot="pre" class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
     <a
       class="font-monospace link-secondary link-underline-secondary link-underline-opacity-0 link-underline-opacity-100-hover small"
@@ -63,7 +69,7 @@ try {
       {file}
     </a>
     <div class="d-flex ms-auto">
-      <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+      <button type="button" class="btn-clipboard mt-0 me-0" title={clipboardLabel}>
         <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"></use></svg>
       </button>
     </div>

From 7bd040a6ba8a23d3c4b45892cf48d7c70b859a76 Mon Sep 17 00:00:00 2001
From: Hannah Issermann <hannah.issermann@orange.com>
Date: Mon, 13 Oct 2025 14:45:03 +0200
Subject: [PATCH 2/3] Change comment to clarify buttonLabel purpose

---
 site/src/components/shortcodes/Code.astro     | 2 +-
 site/src/components/shortcodes/Example.astro  | 2 +-
 site/src/components/shortcodes/JsDocs.astro   | 2 +-
 site/src/components/shortcodes/ScssDocs.astro | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/site/src/components/shortcodes/Code.astro b/site/src/components/shortcodes/Code.astro
index 3b4f5d6c0f..e737b19409 100644
--- a/site/src/components/shortcodes/Code.astro
+++ b/site/src/components/shortcodes/Code.astro
@@ -39,7 +39,7 @@ interface Props {
    */
   nestedInExample?: boolean
   /**
-   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons aria-labels.
    */
   buttonLabel?: string
 }
diff --git a/site/src/components/shortcodes/Example.astro b/site/src/components/shortcodes/Example.astro
index c254942e97..5a04034e98 100644
--- a/site/src/components/shortcodes/Example.astro
+++ b/site/src/components/shortcodes/Example.astro
@@ -37,7 +37,7 @@ interface Props {
    */
   showPreview?: boolean
   /**
-   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons aria-labels.
    */
   buttonLabel?: string
 }
diff --git a/site/src/components/shortcodes/JsDocs.astro b/site/src/components/shortcodes/JsDocs.astro
index 87b8f4f752..1b392b691b 100644
--- a/site/src/components/shortcodes/JsDocs.astro
+++ b/site/src/components/shortcodes/JsDocs.astro
@@ -16,7 +16,7 @@ interface Props {
    */
   file: string
   /**
-   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   * Defines label to complete 'Copy JS to clipboard' button aria-label.
    */
   buttonLabel?: string
 }
diff --git a/site/src/components/shortcodes/ScssDocs.astro b/site/src/components/shortcodes/ScssDocs.astro
index f12a9161f6..748adc5030 100644
--- a/site/src/components/shortcodes/ScssDocs.astro
+++ b/site/src/components/shortcodes/ScssDocs.astro
@@ -16,7 +16,7 @@ interface Props {
    */
   file: string
   /**
-   * Defines label to complete 'Edit code on Stackblitz' and/or 'Copy code to clipboard' buttons labels.
+   * Defines label to complete 'Copy SCSS to clipboard' button aria-label.
    */
   buttonLabel?: string
 }

From 37b131a902f1ad0c3e9d97081b40b1be2a363dde Mon Sep 17 00:00:00 2001
From: Hannah Issermann <hannah.issermann@orange.com>
Date: Tue, 14 Oct 2025 09:46:18 +0200
Subject: [PATCH 3/3] Add an example in docsref

---
 site/src/content/docs/docsref.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/site/src/content/docs/docsref.mdx b/site/src/content/docs/docsref.mdx
index d2311ced09..a62233e85c 100644
--- a/site/src/content/docs/docsref.mdx
+++ b/site/src/content/docs/docsref.mdx
@@ -36,7 +36,7 @@ robots: noindex,follow
 
 <Example showMarkup={false} code={`The <abbr title="HyperText Markup Language">HTML</abbr> abbreviation element.`} />
 
-<Example code={`<div class="test">This is a test.</div>`} />
+<Example buttLabel="test" code={`<div class="test">This is a test.</div>`} />
 
 <ScssDocs name="variable-gradient" file="scss/_variables.scss" />