From 0201cbd382139c203cd7f029eae3d21474146d67 Mon Sep 17 00:00:00 2001
From: Dylan Hyun <dylan.hyun@hashicorp.com>
Date: Thu, 22 May 2025 14:25:04 -0400
Subject: [PATCH 1/2] HDS-3349 `CodeBlock` a11y improvements docs updates

---
 .../components/code-block/partials/code/component-api.md | 9 +++++++++
 .../components/code-block/partials/code/how-to-use.md    | 8 +++++++-
 .../code-editor/partials/code/component-api.md           | 3 +++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/website/docs/components/code-block/partials/code/component-api.md b/website/docs/components/code-block/partials/code/component-api.md
index e1ced3a1dbd..add942551a5 100644
--- a/website/docs/components/code-block/partials/code/component-api.md
+++ b/website/docs/components/code-block/partials/code/component-api.md
@@ -11,6 +11,15 @@ This component uses [prism.js](https://prismjs.com/) under the hood.
   <C.Property @name="<[CB].Description>" @type="yielded component">
     `ContentBlock::Description` yielded as contextual component (see below).
   </C.Property>
+  <C.Property @name="ariaLabel" @type="string">
+    Accepts a localized string. The `ariaLabel` value is applied to the code block pre element.
+  </C.Property>
+  <C.Property @name="ariaLabelledBy" @type="string">
+    Accepts a localized string. The `ariaLabelledBy` value is applied to the code block pre element.
+  </C.Property>
+  <C.Property @name="ariaDescribedBy" @type="string">
+    Accepts a localized string. The `ariaDescribedBy` value is applied to the code block pre element.
+  </C.Property>
   <C.Property @name="value" @type="string" @required={{true}}>
     The text/code content for the `CodeBlock`. The component encodes this argument before displaying it.
   </C.Property>
diff --git a/website/docs/components/code-block/partials/code/how-to-use.md b/website/docs/components/code-block/partials/code/how-to-use.md
index 28214b85448..1de194e3fec 100644
--- a/website/docs/components/code-block/partials/code/how-to-use.md
+++ b/website/docs/components/code-block/partials/code/how-to-use.md
@@ -1,6 +1,6 @@
 ## How to use this component
 
-The basic invocation requires a `@value` argument. The component encodes this argument before displaying it.
+The basic invocation requires a `@value` argument. The component encodes this argument before displaying it. To use this component, you must either include the yielded `Title` component, provide an `@ariaLabel`, or specify an `@ariaLabelledBy`.
 
 !!! Info
 
@@ -10,6 +10,7 @@ If the `\n` escape sequence is used in the `@value` string in Handlebars, it wil
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="basic usage"
   @value="aws ec2 --region us-west-1 accept-vpc-peering-connection"
 />
 ```
@@ -70,6 +71,7 @@ The `language` argument sets the syntax highlighting used. We only support the f
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="language"
   @language="go"
   @value="package main
 import fmt
@@ -85,6 +87,7 @@ Set `hasCopyButton` to `true` to display a button for users to copy `CodeBlock`
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="copy button"
   @language="javascript"
   @hasCopyButton={{true}}
   @copyButtonText="Copy javascript code"
@@ -99,6 +102,7 @@ Line numbers are displayed by default. Set `hasLineNumbers` to `false` to hide t
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="line numbers"
   @language="javascript"
   @hasLineNumbers={{false}}
   @value="let codeLang=`JavaScript`;
@@ -118,6 +122,7 @@ By default, long lines of code will overflow the `CodeBlock` container requiring
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="line wrapping"
   @language="javascript"
   @hasLineWrapping={{true}}
   @value="console.log(`I am JavaScript code`, `Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam`);"
@@ -130,6 +135,7 @@ Highlight either individual code lines or a range of code lines. (Examples: `2,
 
 ```handlebars
 <Hds::CodeBlock
+  @ariaLabel="line highlighting"
   @language="javascript"
   @highlightLines={{"2, 4"}}
   @value="import Application from `@ember/application`;
diff --git a/website/docs/components/code-editor/partials/code/component-api.md b/website/docs/components/code-editor/partials/code/component-api.md
index 98b0591e984..963cdbefcdb 100644
--- a/website/docs/components/code-editor/partials/code/component-api.md
+++ b/website/docs/components/code-editor/partials/code/component-api.md
@@ -20,6 +20,9 @@ This component uses [CodeMirror 6](https://codemirror.net/) under the hood.
   <C.Property @name="ariaLabelledBy" @type="string">
     Accepts a localized string. The `ariaLabelledBy` value is applied to the code editor input element.
   </C.Property>
+  <C.Property @name="ariaDescribedBy" @type="string">
+    Accepts a localized string. The `ariaDescribedBy` value is applied to the code editor input element.
+  </C.Property>
   <C.Property @name="hasCopyButton" @type="boolean" @default="false">
     Used to control whether a copy button for copying the code/text content will be displayed.
   </C.Property>

From c6ee629d5e0259267ac740a651c6ecf28b6a616c Mon Sep 17 00:00:00 2001
From: Dylan Hyun <dylan.hyun@hashicorp.com>
Date: Wed, 4 Jun 2025 14:43:17 -0400
Subject: [PATCH 2/2] Fix: Code Block move aria args text block

---
 .../docs/components/code-block/partials/code/how-to-use.md    | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/website/docs/components/code-block/partials/code/how-to-use.md b/website/docs/components/code-block/partials/code/how-to-use.md
index 1de194e3fec..a8763b3795c 100644
--- a/website/docs/components/code-block/partials/code/how-to-use.md
+++ b/website/docs/components/code-block/partials/code/how-to-use.md
@@ -1,6 +1,8 @@
 ## How to use this component
 
-The basic invocation requires a `@value` argument. The component encodes this argument before displaying it. To use this component, you must either include the yielded `Title` component, provide an `@ariaLabel`, or specify an `@ariaLabelledBy`.
+To use this component, you must either include the yielded `Title` component, provide an `@ariaLabel`, or specify an `@ariaLabelledBy`.
+
+The basic invocation requires a `@value` argument. The component encodes this argument before displaying it.
 
 !!! Info