Skip to content

Website - CodeBlock a11y improvements docs #2896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 4, 2025
Merged

Website - CodeBlock a11y improvements docs #2896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0201cbd
HDS-3349 `CodeBlock` a11y improvements docs updates
dchyun May 22, 2025
c6ee629
Fix: Code Block move aria args text block
dchyun Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions website/docs/components/code-block/partials/code/component-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] why are we saying "localized" here? we don't mention localization in any other parts o the APIs (plus it works even if it's not localized)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was matching the language used for the aria attributes in the component api of the Code Editor docs

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I'll ask the team what they think of this.

</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>
Expand Down
8 changes: 8 additions & 0 deletions website/docs/components/code-block/partials/code/how-to-use.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
## How to use this component

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
Expand All @@ -10,6 +12,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"
/>
```
Expand Down Expand Up @@ -70,6 +73,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
Expand All @@ -85,6 +89,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"
Expand All @@ -99,6 +104,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`;
Expand All @@ -118,6 +124,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`);"
Expand All @@ -130,6 +137,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`;
Expand Down
3 changes: 3 additions & 0 deletions website/docs/components/code-editor/partials/code/component-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down